clawmatrix 0.2.11 → 0.4.0

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2025-2026 Ruiming Zhuang
+
+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.
+
+---
+
+Note: The contents of `contrib/ios-node/` and `contrib/mac-app/` are licensed
+separately under the Business Source License 1.1 (BSL-1.1). See the LICENSE
+files in those directories for details.

package/README.md

@@ -2,19 +2,31 @@
 
 # ClawMatrix
 
-A decentralized mesh cluster plugin that connects multiple [OpenClaw](https://github.com/nicepkg/openclaw) Gateways into a peer-to-peer network, sharing Agents, models, tools, and optionally workspace knowledge files across nodes.
+A decentralized mesh cluster plugin that connects multiple [OpenClaw](https://github.com/nicepkg/openclaw) Gateways into a peer-to-peer network, sharing Agents, models, tools, files, and workspace knowledge across nodes.
 
 > **Warning**: This project is under active development and testing. APIs and protocols may change without notice. Not recommended for production use.
 
 ## Features
 
+**Model Proxy** — No API key on your home node? Use LLMs from intranet nodes through the cluster, as if they were local models. Supports both Chat Completions and Responses API with auto-detection.
+
+**Task Handoff** — Need intranet resources? Delegate tasks to remote Agents with repository access and stream results back. Supports input continuation for mid-task prompts and automatic failover.
+
+**Tool Proxy** — Want to run a command or read a file on a remote node? Call it directly without delegating the entire task. Supports batch invocations in a single round-trip.
+
+**ACP Agent Proxy** — Spawn remote coding agents (Claude Code, Codex, Gemini) on other nodes via ACP protocol with persistent sessions.
+
+**Interactive Terminal** — Open a PTY session on any remote node for interactive shell access.
+
+**File Transfer** — Transfer files up to 100MB between nodes with chunked transfer and SHA-256 integrity check.
+
 **Knowledge Sync (optional)** — Synchronize workspace files such as `MEMORY.md`, `memory/*.md`, `skills/`, and other selected knowledge files across nodes using CRDT + mesh sync, with git-friendly local files as the source of truth.
 
-**Model Proxy** — No API key on your home node? Use LLMs from intranet nodes through the cluster, as if they were local models.
+**Sentinel** — A detached subprocess that survives OpenClaw crashes, maintains peer connections, and handles diagnostic commands when the gateway is down.
 
-**Task Handoff** — Need intranet resources? Delegate tasks to remote Agents with repository access and stream results back.
+**Peer Approval** — Control which nodes can join your mesh with notify or required approval modes. Enabled by default.
 
-**Tool Proxy** — Want to run a command or read a file on a remote node? Call it directly without delegating the entire task.
+**E2EE** — X25519 ECDH end-to-end encryption for all post-handshake frames, enabled by default.
 
 **Auto-Discovery & Failover** — Gossip protocol automatically discovers nodes; requests are rerouted to backups when a node goes down.
 
@@ -79,13 +91,15 @@ Edit `openclaw.json` to add the plugin configuration. All nodes share the same `
   "secret": "your-shared-secret-min-16-chars",
   "peers": [{ "nodeId": "cloud-01", "url": "wss://cloud-01.example.com:19000" }],
   "agents": [{ "id": "assistant", "description": "Personal assistant", "tags": ["general"] }],
-  "proxyModels": [{ "id": "claude-sonnet", "nodeId": "office-01" }]
+  "proxyModels": [
+    { "nodeId": "office-01", "models": [{ "id": "claude-sonnet" }] }
+  ]
 }
 ```
 
 **Important**: Nodes sharing models only need to declare `{ id, provider }` in `models`. ClawMatrix automatically reads the corresponding `baseUrl` and `apiKey` from OpenClaw's `models.providers` and calls the model API directly (bypassing the OpenClaw Gateway's agent system).
 
-Nodes consuming remote models need to register them in `models.providers` (using the nodeId as the key, with baseUrl pointing to `http://127.0.0.1:19001`). See [BOOTSTRAP.md](BOOTSTRAP.md) for details.
+Nodes consuming remote models need to register them in `models.providers` (using the nodeId as the key, with baseUrl pointing to the proxy port). See [BOOTSTRAP.md](BOOTSTRAP.md) for details.
 
 To use a cluster model: `/model <nodeId>/<modelId>`.
 
@@ -103,34 +117,128 @@ After installation, the Agent automatically gains access to the following tools:
 | Tool | Description |
 |------|-------------|
 | `cluster_handoff` | Delegate a task to a remote Agent and wait for the result |
+| `cluster_handoff_reply` | Continue a handoff by sending additional input to the remote Agent |
 | `cluster_send` | Send a one-way message to a remote Agent |
 | `cluster_peers` | View cluster topology and connection status |
 | `cluster_exec` | Execute a command on a remote node |
 | `cluster_read` | Read a file on a remote node |
 | `cluster_write` | Write a file on a remote node |
+| `cluster_edit` | Edit (find-and-replace) a file on a remote node |
+| `cluster_batch` | Execute multiple tools on a remote node in one round-trip |
 | `cluster_tool` | Invoke any OpenClaw tool on a remote node |
+| `cluster_terminal` | Open an interactive PTY session on a remote node |
+| `cluster_transfer` | Transfer files between local and remote nodes (up to 100MB) |
+| `cluster_events` | Query and consume cluster events |
+| `cluster_diagnostic` | Diagnose or exec on a remote node's sentinel (works even when gateway is down) |
+| `cluster_acp` | Spawn a remote coding agent (Claude Code, Codex, Gemini, etc.) via ACP |
 
 The target parameter supports nodeId (`"office-01"`) or tag queries (`"tags:coding"`).
 
 ## Configuration Reference
 
+### Core
+
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
 | `nodeId` | string | required | Unique node identifier |
 | `secret` | string | required | Cluster shared secret (>= 16 characters) |
 | `listen` | boolean | `false` | Accept inbound WS connections |
 | `listenHost` | string | `"0.0.0.0"` | Listen address |
-| `listenPort` | number | `19000` | Inbound WS port |
+| `listenPort` | number | `0` (random) | Inbound WS port |
 | `peers` | array | `[]` | Peers to connect to: `{ nodeId, url }` |
 | `agents` | array | `[]` | Local Agents: `{ id, description, tags }` |
 | `models` | array | `[]` | Models shared with the cluster: `{ id, provider }` (auto-reads OpenClaw provider config; optional `baseUrl`/`apiKey` override) |
-| `proxyModels` | array | `[]` | Remote models to consume: `{ id, nodeId? }` |
-| `tags` | array | `[]` | Free-form tags |
-| `proxyPort` | number | `19001` | Local model proxy port |
+| `proxyModels` | array | `[]` | Remote model groups to consume: `{ nodeId, models: [{ id }] }` |
+| `tags` | array | `[]` | Free-form node tags |
+| `proxyPort` | number | `0` (random) | Local model proxy port |
+| `e2ee` | boolean | `true` | End-to-end encryption (X25519 ECDH) |
+| `compression` | boolean | `false` | Message compression |
+
+### Timeouts
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
 | `handoffTimeout` | number | `600000` | Handoff timeout (ms) |
+| `modelTimeout` | number | `120000` | Model proxy request timeout (ms) |
+| `toolTimeout` | number | `30000` | Tool execution timeout (ms) |
+| `disconnectGrace` | number | `30000` | Grace period before broadcasting peer_leave (ms) |
+
+### Tool Proxy
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
 | `toolProxy.enabled` | boolean | `false` | Allow remote tool execution |
-| `toolProxy.allow` | array | `[]` | Allowed tool names; `["*"]` or `[]` means all. `exec`/`read`/`write`/`edit` run locally, others go through Gateway |
+| `toolProxy.allow` | array | `[]` | Allowed tool names; `["*"]` or `[]` means all |
 | `toolProxy.deny` | array | `[]` | Denied tools (takes precedence over allow) |
+| `toolProxy.maxOutputBytes` | number | `1048576` | Max tool output size (bytes) |
+
+### Peer Approval
+
+Peer approval accepts either a boolean shorthand or an object. The default is `true` (required mode enabled).
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `peerApproval` | boolean \| object | `true` | `true` = required mode, `false` = disabled, or object for fine-grained config |
+| `peerApproval.enabled` | boolean | `false` | Enable peer approval (object form) |
+| `peerApproval.mode` | string | `"notify"` | `"notify"` (log only) or `"required"` (block until approved) |
+| `peerApproval.timeout` | number | `1200000` | Approval request timeout (ms) |
+| `peerApproval.allowList` | array | `[]` | NodeIds that skip approval |
+| `peerApproval.persistPath` | string | `"approved-peers.json"` | Path to store approved peers |
+| `peerApproval.notifyTargets` | array | `[]` | Notification targets: `{ channel, to, accountId?, threadId? }` |
+
+### Terminal
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `terminal.enabled` | boolean | `true` | Allow remote PTY sessions |
+| `terminal.shell` | string | system default | Shell to use |
+| `terminal.sessionTTL` | number | `1800000` | Idle session timeout (ms) |
+| `terminal.maxSessions` | number | `3` | Max concurrent PTY sessions |
+| `terminal.allowFrom` | array | `[]` | Allowed nodeIds (empty = all) |
+
+### File Transfer
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `fileTransfer.enabled` | boolean | `false` | Allow file transfers |
+| `fileTransfer.chunkSize` | number | `262144` | Chunk size in bytes (256KB) |
+| `fileTransfer.maxFileSize` | number | `104857600` | Max file size (100MB) |
+| `fileTransfer.timeout` | number | `300000` | Per-chunk timeout (ms) |
+| `fileTransfer.allowedPaths` | array | `[]` | Allowed paths (empty = no restriction) |
+
+### Knowledge Sync
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `knowledge.enabled` | boolean | `false` | Enable CRDT knowledge sync |
+| `knowledge.paths` | array | `[]` | File/glob patterns to sync |
+| `knowledge.debounce` | number | `5000` | File watch debounce (ms) |
+| `knowledge.maxFileSize` | number | `524288` | Max file size to sync (bytes) |
+
+### ACP Agents
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `acp.enabled` | boolean | `false` | Enable ACP agent proxy |
+| `acp.agents` | array | `[]` | Available agents: `{ id, description }` |
+| `acp.commands` | object | `{}` | Override spawn commands per agent name |
+| `acp.timeout` | number | `600000` | Per-turn timeout (ms) |
+| `acp.sessionTTL` | number | `1800000` | Idle session TTL (ms) |
+| `acp.maxSessions` | number | `5` | Max concurrent ACP sessions |
+
+### Sentinel
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `sentinel.enabled` | boolean | `true` | Enable sentinel subprocess |
+| `sentinel.listenPort` | number | same as `listenPort` | Port sentinel listens on (takes over when gateway dies) |
+
+### Web UI
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `web.enabled` | boolean | `false` | Enable HTTP web interface |
+| `web.token` | string | required if enabled | Auth token (>= 8 characters) |
 
 ## Architecture
 
@@ -149,9 +257,12 @@ The target parameter supports nodeId (`"office-01"`) or tag queries (`"tags:codi
 ```
 
 - Decentralized mesh — no leader, no consensus protocol
-- HMAC-SHA256 challenge-response authentication
+- X25519 TOFU identity + HMAC-SHA256 challenge-response authentication
+- End-to-end encryption via X25519 ECDH (enabled by default)
 - Message relay + TTL loop prevention + ID deduplication
+- Per-IP rate limiting on inbound connections
 - Heartbeat detection + exponential backoff reconnection + automatic failover
+- Sentinel survives gateway crashes and takes over the listen port
 - `wss://` (TLS) recommended for production
 
 ## Development