clew-code 0.2.13 → 0.2.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/main.js +2596 -2527
- package/docs/architecture.html +148 -148
- package/docs/architecture.th.html +79 -79
- package/docs/clew-code-architecture.html +6 -6
- package/docs/commands.html +225 -224
- package/docs/commands.th.html +132 -131
- package/docs/configuration.html +147 -147
- package/docs/configuration.th.html +108 -108
- package/docs/daemon.html +129 -129
- package/docs/daemon.th.html +73 -73
- package/docs/features/bridge-mode.html +99 -99
- package/docs/features/bridge-mode.th.html +90 -90
- package/docs/features/evals.html +182 -182
- package/docs/features/evals.th.html +90 -90
- package/docs/features/peer.html +178 -178
- package/docs/features/searxng-search.html +151 -151
- package/docs/features/searxng-search.th.html +95 -95
- package/docs/features/sentry-setup.html +157 -157
- package/docs/features/sentry-setup.th.html +97 -97
- package/docs/index.html +298 -299
- package/docs/index.th.html +292 -292
- package/docs/installation.html +105 -105
- package/docs/installation.th.html +105 -105
- package/docs/internals/growthbook-ab-testing.html +113 -113
- package/docs/internals/growthbook-ab-testing.th.html +81 -81
- package/docs/internals/hidden-features.html +175 -149
- package/docs/internals/hidden-features.th.html +135 -109
- package/docs/loop.html +181 -181
- package/docs/loop.th.html +227 -227
- package/docs/mcp.html +247 -247
- package/docs/mcp.th.html +207 -207
- package/docs/models.html +110 -111
- package/docs/models.th.html +61 -61
- package/docs/peer.html +236 -236
- package/docs/peer.th.html +280 -280
- package/docs/permission-model.html +102 -102
- package/docs/permission-model.th.html +67 -67
- package/docs/plugins.html +102 -102
- package/docs/plugins.th.html +79 -79
- package/docs/providers.html +126 -126
- package/docs/providers.th.html +80 -80
- package/docs/quick-start.html +93 -93
- package/docs/quick-start.th.html +1 -1
- package/docs/research-memory.html +82 -82
- package/docs/research-memory.th.html +72 -72
- package/docs/skills.html +117 -117
- package/docs/skills.th.html +90 -90
- package/docs/tools.html +170 -170
- package/docs/tools.th.html +84 -84
- package/docs/troubleshooting.html +106 -106
- package/docs/troubleshooting.th.html +85 -85
- package/package.json +162 -164
package/docs/peer.html
CHANGED
|
@@ -1,236 +1,236 @@
|
|
|
1
|
-
<!DOCTYPE html>
|
|
2
|
-
<html lang="en">
|
|
3
|
-
<head>
|
|
4
|
-
<meta charset="UTF-8">
|
|
5
|
-
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
6
|
-
<title>Peer System — Clew</title>
|
|
7
|
-
<meta name="description" content="LAN peer-to-peer system — discovery, messaging, task delegation, and remote execution between Clew instances.">
|
|
8
|
-
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
9
|
-
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
|
10
|
-
<link href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
|
|
11
|
-
<link rel="stylesheet" href="css/styles.css">
|
|
12
|
-
<link rel="icon" type="image/svg+xml" href="./assets/clew.svg">
|
|
13
|
-
</head>
|
|
14
|
-
<body>
|
|
15
|
-
<header class="header"></header>
|
|
16
|
-
<div class="app">
|
|
17
|
-
<aside class="sidebar" id="sidebar"></aside>
|
|
18
|
-
<div class="sidebar-overlay" id="sidebarOverlay"></div>
|
|
19
|
-
<div class="content-wrap">
|
|
20
|
-
<main class="content">
|
|
21
|
-
<div class="breadcrumbs"><a href="index.html">Home</a><span class="sep">/</span><span>Peer System</span></div>
|
|
22
|
-
<h1>Peer System</h1>
|
|
23
|
-
<p class="section-subtitle">LAN peer-to-peer — discover other Clew instances, send messages, delegate tasks, and execute commands remotely.</p>
|
|
24
|
-
|
|
25
|
-
<p>The peer system lives in <code>src/peer/</code> and consists of three core layers: <strong>PeerServer</strong> (HTTP server), <strong>PeerDiscovery</strong> (LAN scanning), and <strong>PeerStore</strong> (in-memory registry).</p>
|
|
26
|
-
|
|
27
|
-
<h2>Architecture</h2>
|
|
28
|
-
<pre><code> ┌─────────────────────────────────────────────────────────────────────────────â”
|
|
29
|
-
│ PEER SYSTEM FLOW │
|
|
30
|
-
└─────────────────────────────────────────────────────────────────────────────┘
|
|
31
|
-
|
|
32
|
-
┌──────────────────────────â”
|
|
33
|
-
│ /peer share │
|
|
34
|
-
│ (Machine A — Worker) │
|
|
35
|
-
└────────────┬─────────────┘
|
|
36
|
-
│
|
|
37
|
-
┌─────────────────┼─────────────────â”
|
|
38
|
-
â–¼ â–¼ â–¼
|
|
39
|
-
┌──────────────┠┌──────────────┠┌──────────────â”
|
|
40
|
-
│ PeerServer │ │PeerDiscovery │ │ PeerStore │
|
|
41
|
-
│ HTTP :random │ │ │ │ (in-memory) │
|
|
42
|
-
│ port │ │ │ │ │
|
|
43
|
-
└──────┬───────┘ └──────┬───────┘ └──────────────┘
|
|
44
|
-
│ │
|
|
45
|
-
│ ┌────────────┼────────────â”
|
|
46
|
-
│ │ │ │
|
|
47
|
-
│ ▼ ▼ ▼
|
|
48
|
-
│ ┌────────┠┌────────┠┌─────────────â”
|
|
49
|
-
│ │ File │ │ UDP │ │ PeerStore │
|
|
50
|
-
│ │ ~/.cl/ │ │multicast│ │ (singleton) │
|
|
51
|
-
│ │ peers/ │ │239... │ │ │
|
|
52
|
-
│ │{pid}. │ │:42069 │ │ │
|
|
53
|
-
│ │ json │ │ │ │ │
|
|
54
|
-
│ └────┬───┘ └────┬───┘ └─────────────┘
|
|
55
|
-
│ │ │
|
|
56
|
-
│ │ │ heartbeat every 30s
|
|
57
|
-
│ │ │ stale timeout 90s
|
|
58
|
-
│ │ │
|
|
59
|
-
â–¼ â–¼ â–¼
|
|
60
|
-
┌─────────────────────────────────────────────────────â”
|
|
61
|
-
│ LAN NETWORK │
|
|
62
|
-
│ │
|
|
63
|
-
│ ┌─────────┠┌─────────┠│
|
|
64
|
-
│ │ Machine B│◄───────►│ Machine C│ ... │
|
|
65
|
-
│ │ Clew Code│ query │ Clew Code│ │
|
|
66
|
-
│ └────┬─────┘ └────┬─────┘ │
|
|
67
|
-
│ │ │ │
|
|
68
|
-
└────────┼────────────────────┼─────────────────────────┘
|
|
69
|
-
│ │
|
|
70
|
-
│ /peer discover │ /peer discover
|
|
71
|
-
â–¼ â–¼
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
â•â•â• WORKER (Machine A) ENDPOINTS â•â•â•
|
|
75
|
-
|
|
76
|
-
Peer à¸à¸·à¹ˆà¸™ POST /peer-info ──► { hostname, ip, cwd, shell, ... }
|
|
77
|
-
│ POST /peer-msg ──► receive chat message
|
|
78
|
-
├───────────────► POST /peer-todo ──► receive task (goes to inbox)
|
|
79
|
-
│ POST /peer-exec ──► run shell command + return stdout/stderr
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
â•â•â• CLIENT (Machine B) TOOLS â•â•â•
|
|
83
|
-
|
|
84
|
-
/peer discover ──► scan files + UDP query (3s timeout)
|
|
85
|
-
│
|
|
86
|
-
â–¼
|
|
87
|
-
[peer list]
|
|
88
|
-
│
|
|
89
|
-
┌───────────────────┼───────────────────â”
|
|
90
|
-
â–¼ â–¼ â–¼
|
|
91
|
-
/peer join /peer send_task /peer run
|
|
92
|
-
(POST /peer-info) (POST /peer-todo) (POST /peer-exec)
|
|
93
|
-
|
|
94
|
-
│
|
|
95
|
-
â–¼
|
|
96
|
-
/peer send_message ──► POST /peer-msg ──► destination inbox
|
|
97
|
-
/peer broadcast ──► POST /peer-msg ──► all connected peers
|
|
98
|
-
/peer ping ──► GET /peer-info ──► check alive
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
â•â•â• DAEMON (agentLoop.ts) â•â•â•
|
|
102
|
-
|
|
103
|
-
┌───────────────────────────────────â”
|
|
104
|
-
│ Autonomous Agent Loop │
|
|
105
|
-
│ - listens /peer-todo 24/7 │
|
|
106
|
-
│ - receives tasks from peers │
|
|
107
|
-
│ - executes in background worker │
|
|
108
|
-
│ - max 3 concurrent workers │
|
|
109
|
-
└───────────────────────────────────┘
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
â•â•â• DATA LIFECYCLE â•â•â•
|
|
113
|
-
|
|
114
|
-
advertise ──► heartbeat every 30s
|
|
115
|
-
│
|
|
116
|
-
├── 90s no heartbeat ──► stale → evict
|
|
117
|
-
│
|
|
118
|
-
stop share ──► send UDP "offline"
|
|
119
|
-
delete peer file
|
|
120
|
-
close HTTP server</code></pre>
|
|
121
|
-
|
|
122
|
-
<h2>Core Components</h2>
|
|
123
|
-
|
|
124
|
-
<h3>PeerServer <code>src/peer/PeerServer.ts</code></h3>
|
|
125
|
-
<p>Lightweight HTTP server started on a random OS-assigned port when <code>/peer share</code> is invoked. Each endpoint handles a different peer interaction:</p>
|
|
126
|
-
<table>
|
|
127
|
-
<tr><th>Endpoint</th><th>Method</th><th>Purpose</th></tr>
|
|
128
|
-
<tr><td><code>/peer-info</code></td><td>GET</td><td>Return peer metadata (hostname, IP, cwd, shell, platform)</td></tr>
|
|
129
|
-
<tr><td><code>/peer-msg</code></td><td>POST</td><td>Receive a chat message from another peer</td></tr>
|
|
130
|
-
<tr><td><code>/peer-todo</code></td><td>POST</td><td>Receive a task delegation from another peer</td></tr>
|
|
131
|
-
<tr><td><code>/peer-exec</code></td><td>POST</td><td>Execute a shell command and return stdout/stderr</td></tr>
|
|
132
|
-
</table>
|
|
133
|
-
|
|
134
|
-
<h3>PeerDiscovery <code>src/peer/PeerDiscovery.ts</code></h3>
|
|
135
|
-
<p>Two discovery mechanisms work together:</p>
|
|
136
|
-
<ul>
|
|
137
|
-
<li><strong>File-based</strong> — Each instance writes <code>~/.claude/peers/{pid}.json</code> with hostname, IP, port, shell, cwd. Other instances scan this directory to discover local peers.</li>
|
|
138
|
-
<li><strong>UDP Multicast</strong> — Broadcasts heartbeat beacons to <code>239.255.37.37:42069</code> every 30 seconds. Responds to <code>clew-peer-query</code> with <code>clew-peer-info</code>. Cross-machine only.</li>
|
|
139
|
-
<li><strong>Stale eviction</strong> — Peers unseen for 90 seconds (<code>PEER_STALE_TIMEOUT</code>) are automatically removed.</li>
|
|
140
|
-
</ul>
|
|
141
|
-
|
|
142
|
-
<h3>PeerStore <code>src/peer/PeerStore.ts</code></h3>
|
|
143
|
-
<p>Singleton in-memory registry holding all known peers (discovered + explicitly joined), chat messages, todos, and custom tags (display names, roles).</p>
|
|
144
|
-
<ul>
|
|
145
|
-
<li><strong>Discovered peers</strong> — Auto-evicted after stale timeout</li>
|
|
146
|
-
<li><strong>Joined connections</strong> — Persistent; never auto-cleaned</li>
|
|
147
|
-
<li><strong>Tags</strong> — Custom display names and roles per peer</li>
|
|
148
|
-
</ul>
|
|
149
|
-
|
|
150
|
-
<h2>Discovery Protocol</h2>
|
|
151
|
-
<pre><code>DiscoveryMessage =
|
|
152
|
-
| { type: "clew-peer-query", version: 1 } // broadcast scan
|
|
153
|
-
| { type: "clew-peer-info", version: 1, // heartbeat / response
|
|
154
|
-
id: string, hostname: string, ip: string, port: number,
|
|
155
|
-
cwd: string, sessionId?: string, appVersion: string,
|
|
156
|
-
shell?: string, platform?: string, term?: string,
|
|
157
|
-
status: "online" | "offline" }
|
|
158
|
-
|
|
159
|
-
UDP port: 42069
|
|
160
|
-
Multicast IP: 239.255.37.37
|
|
161
|
-
Heartbeat: every 30 seconds
|
|
162
|
-
Stale after: 90 seconds</code></pre>
|
|
163
|
-
|
|
164
|
-
<h2>Commands</h2>
|
|
165
|
-
<table>
|
|
166
|
-
<tr><th>Command</th><th>Description</th></tr>
|
|
167
|
-
<tr><td><code>/peer</code></td><td>Open interactive peer menu (share, join, discover, inbox)</td></tr>
|
|
168
|
-
<tr><td><code>/peer share</code></td><td>Start advertising this instance as a worker on the LAN</td></tr>
|
|
169
|
-
<tr><td><code>/peer stop</code></td><td>Stop advertising and shut down the peer server</td></tr>
|
|
170
|
-
<tr><td><code>/peer discover</code></td><td>Scan for available peers (file + UDP, 3s timeout)</td></tr>
|
|
171
|
-
<tr><td><code>/peer join <host> <port></code></td><td>Connect to a remote peer by host and port</td></tr>
|
|
172
|
-
<tr><td><code>/peer name <name></code></td><td>Set a custom display name for yourself</td></tr>
|
|
173
|
-
<tr><td><code>/peer role <role></code></td><td>Set a role label (builder, tester, deployer, etc.)</td></tr>
|
|
174
|
-
<tr><td><code>/peer inbox</code></td><td>View pending messages and todos from peers</td></tr>
|
|
175
|
-
<tr><td><code>/peer disconnect <peer></code></td><td>Disconnect from a specific peer</td></tr>
|
|
176
|
-
<tr><td><code>/peer todos</code></td><td>List all received tasks</td></tr>
|
|
177
|
-
<tr><td><code>/peer todo done <id></code></td><td>Mark a received task as done</td></tr>
|
|
178
|
-
</table>
|
|
179
|
-
|
|
180
|
-
<h2>AI Tools</h2>
|
|
181
|
-
<p>These are the tools the AI agent uses to interact with the peer system:</p>
|
|
182
|
-
<table>
|
|
183
|
-
<tr><th>Tool</th><th>Description</th></tr>
|
|
184
|
-
<tr><td><code>peer_discover</code></td><td>Scan LAN for available Clew workers</td></tr>
|
|
185
|
-
<tr><td><code>peer_join</code></td><td>Connect to a remote peer via HTTP</td></tr>
|
|
186
|
-
<tr><td><code>peer_ping</code></td><td>Check if a peer is online (GET /peer-info)</td></tr>
|
|
187
|
-
<tr><td><code>peer_info</code></td><td>Fetch detailed peer information</td></tr>
|
|
188
|
-
<tr><td><code>peer_send_message</code></td><td>Send a chat message to a peer</td></tr>
|
|
189
|
-
<tr><td><code>peer_send_task</code></td><td>Assign a task to a remote worker</td></tr>
|
|
190
|
-
<tr><td><code>peer_broadcast</code></td><td>Send a task to all connected peers simultaneously</td></tr>
|
|
191
|
-
<tr><td><code>peer_run</code></td><td>Execute a shell command on a remote worker</td></tr>
|
|
192
|
-
<tr><td><code>peer_disconnect</code></td><td>Remove a peer from the connection list</td></tr>
|
|
193
|
-
<tr><td><code>peer_list_messages</code></td><td>List all received chat messages</td></tr>
|
|
194
|
-
<tr><td><code>peer_list_roles</code></td><td>List all peers with their roles</td></tr>
|
|
195
|
-
<tr><td><code>peer_list_tasks</code></td><td>List all task assignments and their status</td></tr>
|
|
196
|
-
<tr><td><code>peer_set_name</code></td><td>Assign a custom display name to a peer</td></tr>
|
|
197
|
-
<tr><td><code>peer_set_role</code></td><td>Assign a functional role to a peer</td></tr>
|
|
198
|
-
<tr><td><code>peer_share</code></td><td>Toggle sharing (start/stop/status)</td></tr>
|
|
199
|
-
</table>
|
|
200
|
-
|
|
201
|
-
<h2>DAEMON Integration</h2>
|
|
202
|
-
<p>The autonomous agent loop (<code>src/services/autonomous/agentLoop.ts</code>) integrates with PeerServer to accept tasks from remote peers:</p>
|
|
203
|
-
<ul>
|
|
204
|
-
<li>Listens for incoming <code>/peer-todo</code> POSTs 24/7</li>
|
|
205
|
-
<li>Queues received tasks and processes them in background workers</li>
|
|
206
|
-
<li>Max 3 concurrent workers; tasks time out after 30 minutes</li>
|
|
207
|
-
<li>Results are available via <code>/peer todos</code> and <code>/tasks</code></li>
|
|
208
|
-
</ul>
|
|
209
|
-
|
|
210
|
-
<h2>Architecture Files</h2>
|
|
211
|
-
<table>
|
|
212
|
-
<tr><th>File</th><th>Role</th></tr>
|
|
213
|
-
<tr><td><code>src/peer/PeerServer.ts</code></td><td>HTTP server with /peer-info, /peer-msg, /peer-todo, /peer-exec endpoints</td></tr>
|
|
214
|
-
<tr><td><code>src/peer/PeerDiscovery.ts</code></td><td>File-based + UDP multicast LAN peer discovery</td></tr>
|
|
215
|
-
<tr><td><code>src/peer/PeerStore.ts</code></td><td>In-memory singleton registry (peers, messages, todos, tags)</td></tr>
|
|
216
|
-
<tr><td><code>src/peer/types.ts</code></td><td>Shared types and protocol constants</td></tr>
|
|
217
|
-
<tr><td><code>src/commands/peer/</code></td><td>Interactive peer menu and CLI commands</td></tr>
|
|
218
|
-
<tr><td><code>src/tools/Peer*Tool/</code></td><td>16 AI agent tools wrapping peer operations</td></tr>
|
|
219
|
-
<tr><td><code>src/services/autonomous/agentLoop.ts</code></td><td>Daemon integration: accepts remote tasks via PeerServer</td></tr>
|
|
220
|
-
</table>
|
|
221
|
-
|
|
222
|
-
<footer class="footer">
|
|
223
|
-
<span>Clew Code
|
|
224
|
-
<div class="footer-links">
|
|
225
|
-
<a href="https://github.com/ClewCode/ClewCode">GitHub</a>
|
|
226
|
-
<a href="https://github.com/ClewCode/ClewCode/issues">Issues</a>
|
|
227
|
-
</div>
|
|
228
|
-
</footer>
|
|
229
|
-
</main>
|
|
230
|
-
<nav class="toc-sidebar"></nav>
|
|
231
|
-
</div>
|
|
232
|
-
</div>
|
|
233
|
-
<script src="js/main.js"></script>
|
|
234
|
-
</body>
|
|
235
|
-
</html>
|
|
236
|
-
|
|
1
|
+
<!DOCTYPE html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="UTF-8">
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
6
|
+
<title>Peer System — Clew</title>
|
|
7
|
+
<meta name="description" content="LAN peer-to-peer system — discovery, messaging, task delegation, and remote execution between Clew instances.">
|
|
8
|
+
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
9
|
+
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
|
10
|
+
<link href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
|
|
11
|
+
<link rel="stylesheet" href="css/styles.css">
|
|
12
|
+
<link rel="icon" type="image/svg+xml" href="./assets/clew.svg">
|
|
13
|
+
</head>
|
|
14
|
+
<body>
|
|
15
|
+
<header class="header"></header>
|
|
16
|
+
<div class="app">
|
|
17
|
+
<aside class="sidebar" id="sidebar"></aside>
|
|
18
|
+
<div class="sidebar-overlay" id="sidebarOverlay"></div>
|
|
19
|
+
<div class="content-wrap">
|
|
20
|
+
<main class="content">
|
|
21
|
+
<div class="breadcrumbs"><a href="index.html">Home</a><span class="sep">/</span><span>Peer System</span></div>
|
|
22
|
+
<h1>Peer System</h1>
|
|
23
|
+
<p class="section-subtitle">LAN peer-to-peer — discover other Clew instances, send messages, delegate tasks, and execute commands remotely.</p>
|
|
24
|
+
|
|
25
|
+
<p>The peer system lives in <code>src/peer/</code> and consists of three core layers: <strong>PeerServer</strong> (HTTP server), <strong>PeerDiscovery</strong> (LAN scanning), and <strong>PeerStore</strong> (in-memory registry).</p>
|
|
26
|
+
|
|
27
|
+
<h2>Architecture</h2>
|
|
28
|
+
<pre><code> ┌─────────────────────────────────────────────────────────────────────────────â”
|
|
29
|
+
│ PEER SYSTEM FLOW │
|
|
30
|
+
└─────────────────────────────────────────────────────────────────────────────┘
|
|
31
|
+
|
|
32
|
+
┌──────────────────────────â”
|
|
33
|
+
│ /peer share │
|
|
34
|
+
│ (Machine A — Worker) │
|
|
35
|
+
└────────────┬─────────────┘
|
|
36
|
+
│
|
|
37
|
+
┌─────────────────┼─────────────────â”
|
|
38
|
+
â–¼ â–¼ â–¼
|
|
39
|
+
┌──────────────┠┌──────────────┠┌──────────────â”
|
|
40
|
+
│ PeerServer │ │PeerDiscovery │ │ PeerStore │
|
|
41
|
+
│ HTTP :random │ │ │ │ (in-memory) │
|
|
42
|
+
│ port │ │ │ │ │
|
|
43
|
+
└──────┬───────┘ └──────┬───────┘ └──────────────┘
|
|
44
|
+
│ │
|
|
45
|
+
│ ┌────────────┼────────────â”
|
|
46
|
+
│ │ │ │
|
|
47
|
+
│ ▼ ▼ ▼
|
|
48
|
+
│ ┌────────┠┌────────┠┌─────────────â”
|
|
49
|
+
│ │ File │ │ UDP │ │ PeerStore │
|
|
50
|
+
│ │ ~/.cl/ │ │multicast│ │ (singleton) │
|
|
51
|
+
│ │ peers/ │ │239... │ │ │
|
|
52
|
+
│ │{pid}. │ │:42069 │ │ │
|
|
53
|
+
│ │ json │ │ │ │ │
|
|
54
|
+
│ └────┬───┘ └────┬───┘ └─────────────┘
|
|
55
|
+
│ │ │
|
|
56
|
+
│ │ │ heartbeat every 30s
|
|
57
|
+
│ │ │ stale timeout 90s
|
|
58
|
+
│ │ │
|
|
59
|
+
â–¼ â–¼ â–¼
|
|
60
|
+
┌─────────────────────────────────────────────────────â”
|
|
61
|
+
│ LAN NETWORK │
|
|
62
|
+
│ │
|
|
63
|
+
│ ┌─────────┠┌─────────┠│
|
|
64
|
+
│ │ Machine B│◄───────►│ Machine C│ ... │
|
|
65
|
+
│ │ Clew Code│ query │ Clew Code│ │
|
|
66
|
+
│ └────┬─────┘ └────┬─────┘ │
|
|
67
|
+
│ │ │ │
|
|
68
|
+
└────────┼────────────────────┼─────────────────────────┘
|
|
69
|
+
│ │
|
|
70
|
+
│ /peer discover │ /peer discover
|
|
71
|
+
â–¼ â–¼
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
â•â•â• WORKER (Machine A) ENDPOINTS â•â•â•
|
|
75
|
+
|
|
76
|
+
Peer à¸à¸·à¹ˆà¸™ POST /peer-info ──► { hostname, ip, cwd, shell, ... }
|
|
77
|
+
│ POST /peer-msg ──► receive chat message
|
|
78
|
+
├───────────────► POST /peer-todo ──► receive task (goes to inbox)
|
|
79
|
+
│ POST /peer-exec ──► run shell command + return stdout/stderr
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
â•â•â• CLIENT (Machine B) TOOLS â•â•â•
|
|
83
|
+
|
|
84
|
+
/peer discover ──► scan files + UDP query (3s timeout)
|
|
85
|
+
│
|
|
86
|
+
â–¼
|
|
87
|
+
[peer list]
|
|
88
|
+
│
|
|
89
|
+
┌───────────────────┼───────────────────â”
|
|
90
|
+
â–¼ â–¼ â–¼
|
|
91
|
+
/peer join /peer send_task /peer run
|
|
92
|
+
(POST /peer-info) (POST /peer-todo) (POST /peer-exec)
|
|
93
|
+
|
|
94
|
+
│
|
|
95
|
+
â–¼
|
|
96
|
+
/peer send_message ──► POST /peer-msg ──► destination inbox
|
|
97
|
+
/peer broadcast ──► POST /peer-msg ──► all connected peers
|
|
98
|
+
/peer ping ──► GET /peer-info ──► check alive
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
â•â•â• DAEMON (agentLoop.ts) â•â•â•
|
|
102
|
+
|
|
103
|
+
┌───────────────────────────────────â”
|
|
104
|
+
│ Autonomous Agent Loop │
|
|
105
|
+
│ - listens /peer-todo 24/7 │
|
|
106
|
+
│ - receives tasks from peers │
|
|
107
|
+
│ - executes in background worker │
|
|
108
|
+
│ - max 3 concurrent workers │
|
|
109
|
+
└───────────────────────────────────┘
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
â•â•â• DATA LIFECYCLE â•â•â•
|
|
113
|
+
|
|
114
|
+
advertise ──► heartbeat every 30s
|
|
115
|
+
│
|
|
116
|
+
├── 90s no heartbeat ──► stale → evict
|
|
117
|
+
│
|
|
118
|
+
stop share ──► send UDP "offline"
|
|
119
|
+
delete peer file
|
|
120
|
+
close HTTP server</code></pre>
|
|
121
|
+
|
|
122
|
+
<h2>Core Components</h2>
|
|
123
|
+
|
|
124
|
+
<h3>PeerServer <code>src/peer/PeerServer.ts</code></h3>
|
|
125
|
+
<p>Lightweight HTTP server started on a random OS-assigned port when <code>/peer share</code> is invoked. Each endpoint handles a different peer interaction:</p>
|
|
126
|
+
<table>
|
|
127
|
+
<tr><th>Endpoint</th><th>Method</th><th>Purpose</th></tr>
|
|
128
|
+
<tr><td><code>/peer-info</code></td><td>GET</td><td>Return peer metadata (hostname, IP, cwd, shell, platform)</td></tr>
|
|
129
|
+
<tr><td><code>/peer-msg</code></td><td>POST</td><td>Receive a chat message from another peer</td></tr>
|
|
130
|
+
<tr><td><code>/peer-todo</code></td><td>POST</td><td>Receive a task delegation from another peer</td></tr>
|
|
131
|
+
<tr><td><code>/peer-exec</code></td><td>POST</td><td>Execute a shell command and return stdout/stderr</td></tr>
|
|
132
|
+
</table>
|
|
133
|
+
|
|
134
|
+
<h3>PeerDiscovery <code>src/peer/PeerDiscovery.ts</code></h3>
|
|
135
|
+
<p>Two discovery mechanisms work together:</p>
|
|
136
|
+
<ul>
|
|
137
|
+
<li><strong>File-based</strong> — Each instance writes <code>~/.claude/peers/{pid}.json</code> with hostname, IP, port, shell, cwd. Other instances scan this directory to discover local peers.</li>
|
|
138
|
+
<li><strong>UDP Multicast</strong> — Broadcasts heartbeat beacons to <code>239.255.37.37:42069</code> every 30 seconds. Responds to <code>clew-peer-query</code> with <code>clew-peer-info</code>. Cross-machine only.</li>
|
|
139
|
+
<li><strong>Stale eviction</strong> — Peers unseen for 90 seconds (<code>PEER_STALE_TIMEOUT</code>) are automatically removed.</li>
|
|
140
|
+
</ul>
|
|
141
|
+
|
|
142
|
+
<h3>PeerStore <code>src/peer/PeerStore.ts</code></h3>
|
|
143
|
+
<p>Singleton in-memory registry holding all known peers (discovered + explicitly joined), chat messages, todos, and custom tags (display names, roles).</p>
|
|
144
|
+
<ul>
|
|
145
|
+
<li><strong>Discovered peers</strong> — Auto-evicted after stale timeout</li>
|
|
146
|
+
<li><strong>Joined connections</strong> — Persistent; never auto-cleaned</li>
|
|
147
|
+
<li><strong>Tags</strong> — Custom display names and roles per peer</li>
|
|
148
|
+
</ul>
|
|
149
|
+
|
|
150
|
+
<h2>Discovery Protocol</h2>
|
|
151
|
+
<pre><code>DiscoveryMessage =
|
|
152
|
+
| { type: "clew-peer-query", version: 1 } // broadcast scan
|
|
153
|
+
| { type: "clew-peer-info", version: 1, // heartbeat / response
|
|
154
|
+
id: string, hostname: string, ip: string, port: number,
|
|
155
|
+
cwd: string, sessionId?: string, appVersion: string,
|
|
156
|
+
shell?: string, platform?: string, term?: string,
|
|
157
|
+
status: "online" | "offline" }
|
|
158
|
+
|
|
159
|
+
UDP port: 42069
|
|
160
|
+
Multicast IP: 239.255.37.37
|
|
161
|
+
Heartbeat: every 30 seconds
|
|
162
|
+
Stale after: 90 seconds</code></pre>
|
|
163
|
+
|
|
164
|
+
<h2>Commands</h2>
|
|
165
|
+
<table>
|
|
166
|
+
<tr><th>Command</th><th>Description</th></tr>
|
|
167
|
+
<tr><td><code>/peer</code></td><td>Open interactive peer menu (share, join, discover, inbox)</td></tr>
|
|
168
|
+
<tr><td><code>/peer share</code></td><td>Start advertising this instance as a worker on the LAN</td></tr>
|
|
169
|
+
<tr><td><code>/peer stop</code></td><td>Stop advertising and shut down the peer server</td></tr>
|
|
170
|
+
<tr><td><code>/peer discover</code></td><td>Scan for available peers (file + UDP, 3s timeout)</td></tr>
|
|
171
|
+
<tr><td><code>/peer join <host> <port></code></td><td>Connect to a remote peer by host and port</td></tr>
|
|
172
|
+
<tr><td><code>/peer name <name></code></td><td>Set a custom display name for yourself</td></tr>
|
|
173
|
+
<tr><td><code>/peer role <role></code></td><td>Set a role label (builder, tester, deployer, etc.)</td></tr>
|
|
174
|
+
<tr><td><code>/peer inbox</code></td><td>View pending messages and todos from peers</td></tr>
|
|
175
|
+
<tr><td><code>/peer disconnect <peer></code></td><td>Disconnect from a specific peer</td></tr>
|
|
176
|
+
<tr><td><code>/peer todos</code></td><td>List all received tasks</td></tr>
|
|
177
|
+
<tr><td><code>/peer todo done <id></code></td><td>Mark a received task as done</td></tr>
|
|
178
|
+
</table>
|
|
179
|
+
|
|
180
|
+
<h2>AI Tools</h2>
|
|
181
|
+
<p>These are the tools the AI agent uses to interact with the peer system:</p>
|
|
182
|
+
<table>
|
|
183
|
+
<tr><th>Tool</th><th>Description</th></tr>
|
|
184
|
+
<tr><td><code>peer_discover</code></td><td>Scan LAN for available Clew workers</td></tr>
|
|
185
|
+
<tr><td><code>peer_join</code></td><td>Connect to a remote peer via HTTP</td></tr>
|
|
186
|
+
<tr><td><code>peer_ping</code></td><td>Check if a peer is online (GET /peer-info)</td></tr>
|
|
187
|
+
<tr><td><code>peer_info</code></td><td>Fetch detailed peer information</td></tr>
|
|
188
|
+
<tr><td><code>peer_send_message</code></td><td>Send a chat message to a peer</td></tr>
|
|
189
|
+
<tr><td><code>peer_send_task</code></td><td>Assign a task to a remote worker</td></tr>
|
|
190
|
+
<tr><td><code>peer_broadcast</code></td><td>Send a task to all connected peers simultaneously</td></tr>
|
|
191
|
+
<tr><td><code>peer_run</code></td><td>Execute a shell command on a remote worker</td></tr>
|
|
192
|
+
<tr><td><code>peer_disconnect</code></td><td>Remove a peer from the connection list</td></tr>
|
|
193
|
+
<tr><td><code>peer_list_messages</code></td><td>List all received chat messages</td></tr>
|
|
194
|
+
<tr><td><code>peer_list_roles</code></td><td>List all peers with their roles</td></tr>
|
|
195
|
+
<tr><td><code>peer_list_tasks</code></td><td>List all task assignments and their status</td></tr>
|
|
196
|
+
<tr><td><code>peer_set_name</code></td><td>Assign a custom display name to a peer</td></tr>
|
|
197
|
+
<tr><td><code>peer_set_role</code></td><td>Assign a functional role to a peer</td></tr>
|
|
198
|
+
<tr><td><code>peer_share</code></td><td>Toggle sharing (start/stop/status)</td></tr>
|
|
199
|
+
</table>
|
|
200
|
+
|
|
201
|
+
<h2>DAEMON Integration</h2>
|
|
202
|
+
<p>The autonomous agent loop (<code>src/services/autonomous/agentLoop.ts</code>) integrates with PeerServer to accept tasks from remote peers:</p>
|
|
203
|
+
<ul>
|
|
204
|
+
<li>Listens for incoming <code>/peer-todo</code> POSTs 24/7</li>
|
|
205
|
+
<li>Queues received tasks and processes them in background workers</li>
|
|
206
|
+
<li>Max 3 concurrent workers; tasks time out after 30 minutes</li>
|
|
207
|
+
<li>Results are available via <code>/peer todos</code> and <code>/tasks</code></li>
|
|
208
|
+
</ul>
|
|
209
|
+
|
|
210
|
+
<h2>Architecture Files</h2>
|
|
211
|
+
<table>
|
|
212
|
+
<tr><th>File</th><th>Role</th></tr>
|
|
213
|
+
<tr><td><code>src/peer/PeerServer.ts</code></td><td>HTTP server with /peer-info, /peer-msg, /peer-todo, /peer-exec endpoints</td></tr>
|
|
214
|
+
<tr><td><code>src/peer/PeerDiscovery.ts</code></td><td>File-based + UDP multicast LAN peer discovery</td></tr>
|
|
215
|
+
<tr><td><code>src/peer/PeerStore.ts</code></td><td>In-memory singleton registry (peers, messages, todos, tags)</td></tr>
|
|
216
|
+
<tr><td><code>src/peer/types.ts</code></td><td>Shared types and protocol constants</td></tr>
|
|
217
|
+
<tr><td><code>src/commands/peer/</code></td><td>Interactive peer menu and CLI commands</td></tr>
|
|
218
|
+
<tr><td><code>src/tools/Peer*Tool/</code></td><td>16 AI agent tools wrapping peer operations</td></tr>
|
|
219
|
+
<tr><td><code>src/services/autonomous/agentLoop.ts</code></td><td>Daemon integration: accepts remote tasks via PeerServer</td></tr>
|
|
220
|
+
</table>
|
|
221
|
+
|
|
222
|
+
<footer class="footer">
|
|
223
|
+
<span>Clew Code 0.2.13 — Open Source</span>
|
|
224
|
+
<div class="footer-links">
|
|
225
|
+
<a href="https://github.com/ClewCode/ClewCode">GitHub</a>
|
|
226
|
+
<a href="https://github.com/ClewCode/ClewCode/issues">Issues</a>
|
|
227
|
+
</div>
|
|
228
|
+
</footer>
|
|
229
|
+
</main>
|
|
230
|
+
<nav class="toc-sidebar"></nav>
|
|
231
|
+
</div>
|
|
232
|
+
</div>
|
|
233
|
+
<script src="js/main.js"></script>
|
|
234
|
+
</body>
|
|
235
|
+
</html>
|
|
236
|
+
|