clawnexus 0.2.5 → 0.2.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alan Lan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,108 +1,129 @@
-# 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
+# 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` | `/registry/register` | Register with public Registry (v0.2) |
+| `GET` | `/registry/status` | Registration status (v0.2) |
+| `GET` | `/resolve/:name` | Resolve a `.claw` name (v0.2) |
+| `GET` | `/whoami` | This instance's identity (v0.2) |
+| `POST` | `/relay/connect` | Connect via relay (v0.4) |
+| `GET` | `/relay/status` | Relay connection status (v0.4) |
+| `DELETE` | `/relay/disconnect/:room_id` | Disconnect relay room (v0.4) |
+| `GET` | `/agent/policy` | Get agent policy (v0.4) |
+| `PUT` | `/agent/policy` | Replace agent policy (v0.4) |
+| `PATCH` | `/agent/policy` | Partial policy update (v0.4) |
+| `POST` | `/agent/policy/reset` | Reset policy to defaults (v0.4) |
+| `GET` | `/agent/tasks` | List tasks (v0.4) |
+| `GET` | `/agent/tasks/stats` | Task statistics (v0.4) |
+| `GET` | `/agent/tasks/:id` | Get a single task (v0.4) |
+| `POST` | `/agent/tasks/:id/cancel` | Cancel a task (v0.4) |
+| `POST` | `/agent/propose` | Send task proposal to peer (v0.4) |
+| `POST` | `/agent/query` | Query peer capabilities (v0.4) |
+| `GET` | `/agent/inbox` | List queued inbound proposals (v0.4) |
+| `POST` | `/agent/inbox/:id/approve` | Approve queued proposal (v0.4) |
+| `POST` | `/agent/inbox/:id/deny` | Deny queued proposal (v0.4) |
+| `GET` | `/diagnostics` | Full diagnostics summary |
+| `GET` | `/diagnostics/unreachable` | mDNS-heard but unreachable instances |
+
+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` |
+| `CLAWNEXUS_RELAY_URL` | Override relay WebSocket URL | _(from Registry token)_ |
+
+Data is stored in `~/.clawnexus/`:
+
+```
+~/.clawnexus/
+├── registry.json    # Instance registry
+├── daemon.pid       # PID file
+├── identity.json    # Ed25519 identity keys (v0.2)
+└── policy.json      # Agent policy configuration (v0.4)
+```
+
+## 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/registry/store.d.ts

@@ -26,6 +26,21 @@ export declare class RegistryStore extends EventEmitter {
     remove(networkKey: string): boolean;
     setAlias(networkKey: string, alias: string): void;
     get size(): number;
+    /**
+     * Find an existing instance that represents the same physical machine
+     * discovered via a different network interface. Matches on agent_id + lan_host.
+     */
+    private _findDuplicate;
+    /**
+     * Merge two instances representing the same machine on different NICs.
+     * Keeps user-set fields (alias, labels, auto_name, claw_name, owner_pubkey)
+     * from the existing entry. Picks the best address by network scope priority.
+     */
+    private _mergeInstances;
+    /** Numeric priority for network scope: local > vpn > public */
+    private _addressPriority;
+    /** Normalize hostname for comparison: lowercase, strip trailing .local */
+    private _normalizeHost;
     private scheduleDirtyFlush;
     private flushNow;
 }

package/dist/registry/store.js

@@ -201,8 +201,25 @@ class RegistryStore extends node_events_1.EventEmitter {
             // Preserve registry fields
             instance.claw_name = instance.claw_name ?? existing.claw_name;
             instance.owner_pubkey = instance.owner_pubkey ?? existing.owner_pubkey;
+            this.instances.set(key, instance);
+            this.scheduleDirtyFlush();
+            this.emit("upsert", instance);
         }
         else {
+            // Check for duplicate from different NIC (multi-NIC deduplication)
+            const duplicate = this._findDuplicate(instance);
+            if (duplicate) {
+                const merged = this._mergeInstances(duplicate, instance);
+                const oldKey = this.networkKey(duplicate.address, duplicate.gateway_port);
+                const newKey = this.networkKey(merged.address, merged.gateway_port);
+                if (oldKey !== newKey) {
+                    this.instances.delete(oldKey);
+                }
+                this.instances.set(newKey, merged);
+                this.scheduleDirtyFlush();
+                this.emit("merge", { kept: merged, removed_key: oldKey !== newKey ? oldKey : null });
+                return;
+            }
             // First discovery: generate auto_name if not already set
             if (!instance.auto_name) {
                 const baseName = (0, auto_name_js_1.generateAutoName)(instance.lan_host, instance.display_name, instance.address);
@@ -212,10 +229,10 @@ class RegistryStore extends node_events_1.EventEmitter {
                 }
                 instance.auto_name = (0, auto_name_js_1.ensureUnique)(baseName, usedNames);
             }
+            this.instances.set(key, instance);
+            this.scheduleDirtyFlush();
+            this.emit("upsert", instance);
         }
-        this.instances.set(key, instance);
-        this.scheduleDirtyFlush();
-        this.emit("upsert", instance);
     }
     remove(networkKey) {
         const deleted = this.instances.delete(networkKey);
@@ -246,6 +263,72 @@ class RegistryStore extends node_events_1.EventEmitter {
     get size() {
         return this.instances.size;
     }
+    /**
+     * Find an existing instance that represents the same physical machine
+     * discovered via a different network interface. Matches on agent_id + lan_host.
+     */
+    _findDuplicate(instance) {
+        const incomingHost = this._normalizeHost(instance.lan_host);
+        const incomingAgent = instance.agent_id.toLowerCase();
+        for (const existing of this.instances.values()) {
+            if (existing.agent_id.toLowerCase() === incomingAgent &&
+                this._normalizeHost(existing.lan_host) === incomingHost) {
+                return existing;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Merge two instances representing the same machine on different NICs.
+     * Keeps user-set fields (alias, labels, auto_name, claw_name, owner_pubkey)
+     * from the existing entry. Picks the best address by network scope priority.
+     */
+    _mergeInstances(existing, incoming) {
+        const existingPriority = this._addressPriority(existing.network_scope);
+        const incomingPriority = this._addressPriority(incoming.network_scope);
+        // Pick address: higher priority wins; if equal, keep existing (first-seen)
+        const keepExistingAddress = existingPriority >= incomingPriority;
+        return {
+            // Network identity: use the better address
+            address: keepExistingAddress ? existing.address : incoming.address,
+            gateway_port: keepExistingAddress ? existing.gateway_port : incoming.gateway_port,
+            network_scope: keepExistingAddress ? existing.network_scope : incoming.network_scope,
+            tls: keepExistingAddress ? existing.tls : incoming.tls,
+            tls_fingerprint: keepExistingAddress ? existing.tls_fingerprint : incoming.tls_fingerprint,
+            // Identity fields from existing (stable)
+            agent_id: existing.agent_id,
+            auto_name: existing.auto_name,
+            alias: existing.alias,
+            lan_host: existing.lan_host,
+            assistant_name: incoming.assistant_name,
+            display_name: incoming.display_name,
+            // Timestamps: keep original discovered_at, use latest last_seen
+            discovered_at: existing.discovered_at,
+            last_seen: incoming.last_seen,
+            // Discovery source: use the incoming one (most recent discovery)
+            discovery_source: incoming.discovery_source,
+            // Status from incoming (freshest)
+            status: incoming.status,
+            // Preserve user-set and registry fields from existing
+            claw_name: existing.claw_name ?? incoming.claw_name,
+            owner_pubkey: existing.owner_pubkey ?? incoming.owner_pubkey,
+            labels: existing.labels ?? incoming.labels,
+            connectivity: incoming.connectivity ?? existing.connectivity,
+            is_self: existing.is_self || incoming.is_self,
+        };
+    }
+    /** Numeric priority for network scope: local > vpn > public */
+    _addressPriority(scope) {
+        switch (scope) {
+            case "local": return 2;
+            case "vpn": return 1;
+            case "public": return 0;
+        }
+    }
+    /** Normalize hostname for comparison: lowercase, strip trailing .local */
+    _normalizeHost(host) {
+        return host.toLowerCase().replace(/\.local$/, "");
+    }
     scheduleDirtyFlush() {
         this.dirty = true;
         if (this.flushTimer)

package/dist/scanner/active.d.ts

@@ -18,4 +18,13 @@ export declare class ActiveScanner extends EventEmitter {
     private generateIPs;
     private probeAll;
     private probeHost;
+    /**
+     * Resolve a stable lan_host for scanned instances to enable multi-NIC dedup.
+     *
+     * When scanning, we only have the target IP as lan_host. If the same instance
+     * was already discovered via mDNS or LocalProbe (which provide real hostnames),
+     * reuse that hostname so _findDuplicate() can match them as the same machine.
+     */
+    private resolveHostForDedup;
+    private isIPAddress;
 }

package/dist/scanner/active.js

@@ -170,13 +170,16 @@ class ActiveScanner extends node_events_1.EventEmitter {
             const config = (await res.json());
             if (!config.assistantAgentId)
                 return null;
+            // Resolve lan_host: prefer known hostname from existing registry entries
+            // over raw IP to enable multi-NIC deduplication
+            const lan_host = this.resolveHostForDedup(host, port, config.assistantAgentId);
             const now = new Date().toISOString();
             return {
                 agent_id: config.assistantAgentId,
                 auto_name: "", // will be assigned by store.upsert()
                 assistant_name: config.assistantName ?? "",
                 display_name: config.displayName ?? config.assistantName ?? "",
-                lan_host: host,
+                lan_host,
                 address: host,
                 gateway_port: port,
                 tls: false,
@@ -191,6 +194,29 @@ class ActiveScanner extends node_events_1.EventEmitter {
             return null;
         }
     }
+    /**
+     * Resolve a stable lan_host for scanned instances to enable multi-NIC dedup.
+     *
+     * When scanning, we only have the target IP as lan_host. If the same instance
+     * was already discovered via mDNS or LocalProbe (which provide real hostnames),
+     * reuse that hostname so _findDuplicate() can match them as the same machine.
+     */
+    resolveHostForDedup(host, port, agentId) {
+        if (!this.isIPAddress(host))
+            return host;
+        const agentLower = agentId.toLowerCase();
+        for (const existing of this.store.getAll()) {
+            if (existing.agent_id.toLowerCase() === agentLower &&
+                existing.gateway_port === port &&
+                !this.isIPAddress(existing.lan_host)) {
+                return existing.lan_host;
+            }
+        }
+        return host;
+    }
+    isIPAddress(value) {
+        return /^\d{1,3}(\.\d{1,3}){3}$/.test(value);
+    }
 }
 exports.ActiveScanner = ActiveScanner;
 /** Parse "host:port" or "host" into { host, port } */

package/package.json

@@ -1,54 +1,53 @@
-{
-  "name": "clawnexus",
-  "version": "0.2.5",
-  "description": "ClawNexus daemon and CLI — AI instance registry for OpenClaw",
-  "license": "MIT",
-  "author": "alan-silverstreams <alan@silverstream.tech>",
-  "homepage": "https://github.com/alan-silverstreams/ClawNexus",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/alan-silverstreams/ClawNexus.git",
-    "directory": "packages/daemon"
-  },
-  "bugs": "https://github.com/alan-silverstreams/ClawNexus/issues",
-  "keywords": [
-    "openclaw",
-    "ai",
-    "agent",
-    "registry",
-    "mdns",
-    "discovery",
-    "daemon",
-    "cli",
-    "clawnexus"
-  ],
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "bin": {
-    "clawnexus": "dist/cli/index.js"
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "dev": "tsc -p tsconfig.json --watch",
-    "start": "node dist/index.js",
-    "test": "vitest run",
-    "prepublishOnly": "pnpm build"
-  },
-  "engines": {
-    "node": ">=22"
-  },
-  "dependencies": {
-    "fastify": "^5.0.0",
-    "multicast-dns": "^7.2.5",
-    "ws": "^8.18.0"
-  },
-  "devDependencies": {
-    "typescript": "^5.7.0",
-    "@types/node": "^22.0.0",
-    "@types/ws": "^8.5.14"
-  }
-}
+{
+  "name": "clawnexus",
+  "version": "0.2.6",
+  "description": "ClawNexus daemon and CLI — AI instance registry for OpenClaw",
+  "license": "MIT",
+  "author": "alan-silverstreams <alan@silverstream.tech>",
+  "homepage": "https://github.com/SilverstreamsAI/ClawNexus",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SilverstreamsAI/ClawNexus.git",
+    "directory": "packages/daemon"
+  },
+  "bugs": "https://github.com/SilverstreamsAI/ClawNexus/issues",
+  "keywords": [
+    "openclaw",
+    "ai",
+    "agent",
+    "registry",
+    "mdns",
+    "discovery",
+    "daemon",
+    "cli",
+    "clawnexus"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "clawnexus": "dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "fastify": "^5.0.0",
+    "multicast-dns": "^7.2.5",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.14"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run"
+  }
+}