pi-farm 0.2.2 → 0.2.3

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/src/commands.js CHANGED
@@ -25,6 +25,7 @@ import {
25
25
  systemdUserDir,
26
26
  } from "./autostart.js";
27
27
  import { clearStopped, isStopped, markStopped } from "./state.js";
28
+ import { BROADCAST_TARGET, connectPeer, livePeersFor, MeshError, peerPc, probePeers, sessionMeshAddress } from "./mesh.js";
28
29
  import { findCommand, suggestCommand } from "./help.js";
29
30
  import { EXAMPLE_CONFIG } from "./example.js";
30
31
 
@@ -544,6 +545,293 @@ function cmdSend(config, options, ui) {
544
545
  ui.info(`sent to ${session.name}`);
545
546
  }
546
547
 
548
+ function sessionForAddress(config, address) {
549
+ if (!config) return null;
550
+ for (const session of config.sessions) {
551
+ const base = sessionMeshAddress(session);
552
+ if (base && (address === base || address.startsWith(`${base}#`))) return session;
553
+ }
554
+ return null;
555
+ }
556
+
557
+ function meshUsage(ui) {
558
+ ui.error('usage: pp mesh <ls|send|resolve> ... (see "pp help mesh")');
559
+ process.exit(2);
560
+ }
561
+
562
+ async function cmdMesh(config, options, ui) {
563
+ const [sub, ...rest] = options.names;
564
+ switch (sub) {
565
+ case undefined:
566
+ case "ls":
567
+ case "list":
568
+ case "peers":
569
+ return cmdMeshLs(config, options, ui);
570
+ case "send":
571
+ case "msg":
572
+ return cmdMeshSend(config, { ...options, names: rest }, ui);
573
+ case "resolve":
574
+ case "addr":
575
+ return cmdMeshResolve(config, { ...options, names: rest }, ui);
576
+ default:
577
+ ui.error(`unknown mesh subcommand: ${sub}`);
578
+ return meshUsage(ui);
579
+ }
580
+ }
581
+
582
+ async function cmdMeshLs(config, options, ui) {
583
+ let peers;
584
+ try {
585
+ peers = await probePeers({ timeoutMs: options.wait ?? 3000 });
586
+ } catch (err) {
587
+ ui.error(err.message);
588
+ process.exit(1);
589
+ }
590
+ const rows = peers.map((address, index) => {
591
+ const session = sessionForAddress(config, address);
592
+ return {
593
+ index: index + 1,
594
+ address,
595
+ pc: peerPc(address),
596
+ session: session ? session.name : null,
597
+ };
598
+ });
599
+ if (ui.json) {
600
+ ui.out(JSON.stringify(rows, null, 2));
601
+ return;
602
+ }
603
+ if (rows.length === 0) {
604
+ ui.info("no peers in the mesh");
605
+ return;
606
+ }
607
+ const headers = ["#", "ADDRESS", "PC", "SESSION"];
608
+ const table = rows.map((r) => [String(r.index), r.address, r.pc ?? "-", r.session ?? "-"]);
609
+ const widths = headers.map((h, i) => Math.max(h.length, ...table.map((row) => row[i].length)));
610
+ const pad = (value, width) => value + " ".repeat(Math.max(0, width - value.length));
611
+ ui.out(ui.paint("bold", headers.map((h, i) => pad(h, widths[i])).join(" ").trimEnd()));
612
+ table.forEach((row, i) => {
613
+ const cells = [...row];
614
+ cells[0] = ui.paint("dim", cells[0]);
615
+ if (rows[i].session) cells[3] = ui.paint("green", cells[3]);
616
+ ui.out(cells.map((cell, idx) => pad(cell, widths[idx])).join(" ").trimEnd());
617
+ });
618
+ if (!options.quiet) {
619
+ const local = rows.filter((r) => !r.pc).length;
620
+ ui.out(`\n${rows.length} peer(s): ${local} local, ${rows.length - local} cross-PC`);
621
+ }
622
+ }
623
+
624
+ async function cmdMeshResolve(config, options, ui) {
625
+ if (!config) {
626
+ ui.error("no config found; cannot resolve session names (use a raw mesh address instead)");
627
+ process.exit(2);
628
+ }
629
+ const sessions = selectSessions(config, options.names, ui, { all: true });
630
+ let peers = [];
631
+ try {
632
+ peers = await probePeers({ timeoutMs: options.wait ?? 3000 });
633
+ } catch {
634
+ peers = []; // resolving is useful offline; just report the offline state
635
+ }
636
+ const rows = sessions.map((session) => {
637
+ const base = sessionMeshAddress(session);
638
+ const live = livePeersFor(peers, base);
639
+ return {
640
+ name: session.name,
641
+ address: base,
642
+ online: live.length > 0,
643
+ matches: live,
644
+ };
645
+ });
646
+ if (ui.json) {
647
+ ui.out(JSON.stringify(rows, null, 2));
648
+ return;
649
+ }
650
+ for (const row of rows) {
651
+ if (!row.address) {
652
+ ui.out(`${row.name}: no remote-pi name (remote_pi_mode: off?)`);
653
+ continue;
654
+ }
655
+ const state = row.online ? ui.paint("green", `online x${row.matches.length}`) : ui.paint("dim", "offline");
656
+ ui.out(`${row.name} → ${row.address} ${state}`);
657
+ if (row.matches.length > 1) {
658
+ for (const match of row.matches) ui.out(` ${ui.paint("dim", match)}`);
659
+ }
660
+ }
661
+ }
662
+
663
+ async function cmdMeshSend(config, options, ui) {
664
+ const hasBodyJson = options.bodyJson !== undefined;
665
+ if (options.names.length < (hasBodyJson ? 1 : 2)) {
666
+ ui.error('usage: pp mesh send <target...> "text" [--wait <ms>] [--reply <ms>] [--no-wait] [--body-json <json>]');
667
+ process.exit(2);
668
+ }
669
+ const text = hasBodyJson ? null : options.names[options.names.length - 1];
670
+ const rawTargets = hasBodyJson ? options.names : options.names.slice(0, -1);
671
+ let body = text;
672
+ if (hasBodyJson) {
673
+ try {
674
+ body = JSON.parse(options.bodyJson);
675
+ } catch (err) {
676
+ ui.error(`--body-json is not valid JSON: ${err.message}`);
677
+ process.exit(2);
678
+ }
679
+ }
680
+
681
+ // Resolve names/config first: then "unknown session" and a missing config are
682
+ // reported before we bother the broker.
683
+ const wanted = [];
684
+ let broadcast = false;
685
+ for (const raw of rawTargets) {
686
+ if (raw === "all" || raw === "broadcast" || raw === "*") {
687
+ broadcast = true;
688
+ continue;
689
+ }
690
+ if (raw.includes("@") || /^[A-Za-z0-9._-]+:\//.test(raw)) {
691
+ wanted.push({ kind: "address", value: raw });
692
+ continue;
693
+ }
694
+ if (!config) {
695
+ ui.error(`no config found; cannot resolve session "${raw}" (pass a full mesh address instead)`);
696
+ process.exit(2);
697
+ }
698
+ const [session] = selectSessions(config, [raw], ui);
699
+ const base = sessionMeshAddress(session);
700
+ if (!base) {
701
+ ui.error(`"${session.name}" has no remote-pi name (remote_pi_mode: off?)`);
702
+ process.exit(2);
703
+ }
704
+ wanted.push({ kind: "session", value: base, session });
705
+ }
706
+
707
+ let peers = [];
708
+ if (!options.dryRun || wanted.length > 0 || broadcast) {
709
+ try {
710
+ peers = await probePeers({ timeoutMs: options.wait ?? 3000 });
711
+ } catch (err) {
712
+ if (!(err instanceof MeshError) || err.code !== "no_broker") throw err;
713
+ ui.error(err.message);
714
+ process.exit(1);
715
+ }
716
+ }
717
+
718
+ const targets = [];
719
+ for (const item of wanted) {
720
+ const live = livePeersFor(peers, item.value);
721
+ if (live.length === 0) {
722
+ if (item.kind === "address") ui.error(`no peer online at ${item.value}`);
723
+ else ui.error(`"${item.session.name}" is not in the mesh yet (${item.value} is offline; is the session running?)`);
724
+ process.exit(1);
725
+ }
726
+ targets.push(...live);
727
+ }
728
+
729
+ const unique = [...new Set(targets)];
730
+ const multicast = broadcast || unique.length > 1;
731
+ if (!broadcast && unique.length === 0) {
732
+ ui.error("no targets");
733
+ process.exit(2);
734
+ }
735
+ if (options.dryRun) {
736
+ const envelope = { from: options.as ?? "pp-mesh", to: broadcast ? BROADCAST_TARGET : multicast ? unique : unique[0], body };
737
+ ui.info(`[dry-run] ${JSON.stringify(envelope)}`);
738
+ return;
739
+ }
740
+
741
+ let peer;
742
+ try {
743
+ peer = await connectPeer({ name: options.as ?? "pp-mesh", cwd: process.cwd() });
744
+ } catch (err) {
745
+ ui.error(err.message);
746
+ process.exit(1);
747
+ }
748
+ let sendId = null;
749
+ let waitingForFirstReply = null;
750
+ const replies = [];
751
+ const collecting = options.reply !== undefined && options.reply > 0;
752
+ if (collecting) {
753
+ peer.onMessage((envelope) => {
754
+ if (!envelope || envelope.re !== sendId) return;
755
+ replies.push(envelope);
756
+ if (!ui.json) {
757
+ ui.out(`${ui.paint("green", `reply from ${envelope.from}`)}: ${formatMeshBody(envelope.body)}`);
758
+ }
759
+ waitingForFirstReply?.();
760
+ waitingForFirstReply = null;
761
+ });
762
+ }
763
+ const collect = async (single = true) => {
764
+ if (!collecting) return;
765
+ await new Promise((resolve) => {
766
+ const timer = setTimeout(resolve, options.reply);
767
+ if (!single) return;
768
+ waitingForFirstReply = () => {
769
+ clearTimeout(timer);
770
+ resolve();
771
+ };
772
+ });
773
+ waitingForFirstReply = null;
774
+ if (ui.json) {
775
+ ui.out(JSON.stringify(replies, null, 2));
776
+ return replies.length;
777
+ }
778
+ if (replies.length === 0) ui.info(`no reply within ${options.reply}ms (the peer may still be working)`);
779
+ return replies.length;
780
+ };
781
+ try {
782
+ if (broadcast) {
783
+ sendId = peer.send(BROADCAST_TARGET, body);
784
+ ui.info(`broadcast to ${peers.length} peer(s) as ${peer.address} (${sendId})`);
785
+ await collect(false);
786
+ return;
787
+ }
788
+ if (multicast) {
789
+ sendId = peer.send(unique, body);
790
+ ui.info(`sent to ${unique.length} peer(s) as ${peer.address} (${sendId})`);
791
+ for (const target of unique) ui.out(` ${ui.paint("dim", target)}`);
792
+ await collect(false);
793
+ return;
794
+ }
795
+ const target = unique[0];
796
+ if (options.noWait) {
797
+ sendId = peer.send(target, body);
798
+ ui.info(`sent to ${target} (${sendId})`);
799
+ await collect();
800
+ return;
801
+ }
802
+ const ack = await peer.sendWithAck(target, body, options.wait ?? 5000);
803
+ sendId = ack.id;
804
+ if (ack.status === "received") {
805
+ ui.info(`delivered to ${target} (${ack.id})`);
806
+ await collect();
807
+ return;
808
+ }
809
+ if (ack.status === "busy") {
810
+ ui.error(`${target} is mid-turn: broker dropped the message (busy). Retry later or use --no-wait.`);
811
+ process.exitCode = 1;
812
+ return;
813
+ }
814
+ if (ack.status === "denied") {
815
+ ui.error(`delivery to ${target} was denied by the broker`);
816
+ process.exitCode = 1;
817
+ return;
818
+ }
819
+ ui.error(`no ACK from ${target} within ${options.wait ?? 5000}ms (the message may still arrive)`);
820
+ process.exitCode = 1;
821
+ } finally {
822
+ peer.close();
823
+ }
824
+ }
825
+
826
+ function formatMeshBody(body) {
827
+ if (typeof body === "string") return body;
828
+ try {
829
+ return JSON.stringify(body);
830
+ } catch {
831
+ return String(body);
832
+ }
833
+ }
834
+
547
835
  function cmdCheck(config, options, ui) {
548
836
  const tmux = makeTmux(config, options);
549
837
  const problems = [];
@@ -789,6 +1077,15 @@ export async function runCommand(command, options) {
789
1077
  const config = requireConfig(options, ui);
790
1078
  return cmdSend(config, options, ui);
791
1079
  }
1080
+ case "mesh": {
1081
+ let config = null;
1082
+ try {
1083
+ config = loadConfig({ configPath: options.config, cwd: options.cwd });
1084
+ } catch {
1085
+ config = null; // raw addresses and `pp mesh ls` work without a config
1086
+ }
1087
+ return cmdMesh(config, options, ui);
1088
+ }
792
1089
  case "check":
793
1090
  case "validate": {
794
1091
  const config = requireConfig(options, ui);
package/src/help.js CHANGED
@@ -154,6 +154,48 @@ export const COMMANDS = [
154
154
  examples: ['pp send backend "run the tests"', 'pp send 3 "yes" --no-enter'],
155
155
  see: ["logs", "attach"],
156
156
  },
157
+ {
158
+ name: "mesh",
159
+ aliases: [],
160
+ summary: "Talk to the remote-pi agent mesh (ls / send / resolve)",
161
+ usage: "pp mesh <ls|send|resolve> ...",
162
+ details: [
163
+ "pp talks to remote-pi's local broker directly over its UNIX socket",
164
+ "(~/.pi/remote/sessions/local/broker.sock) — no dependencies, no pi needed.",
165
+ "",
166
+ " ls list every peer in the mesh (read-only probe: it never registers,",
167
+ " so nobody sees a peer_joined/peer_left because of it)",
168
+ " resolve map a configured session to its mesh address and online state",
169
+ " send register as an ephemeral peer (default name pp-mesh), deliver the",
170
+ " text, and wait for the broker ACK",
171
+ "",
172
+ "Targets may be a session name or #index (resolved through the config), a raw",
173
+ "mesh address (<cwd>@<name>, or macbook:/path@name for cross-PC), `all`, or",
174
+ "`broadcast`. One target = unicast with ACK (received/busy/denied/timeout);",
175
+ "several targets or `all` = multicast, fire-and-forget.",
176
+ "",
177
+ "A busy peer drops the message (broker ACK `busy`) — retry later or --no-wait.",
178
+ "Cross-PC delivery rides the broker leader's relay bridge, so no pairing.",
179
+ ].join("\n"),
180
+ options: [
181
+ "--json JSON output (ls/resolve)",
182
+ "--as <name> mesh name to register as (default: pp-mesh)",
183
+ "--wait <ms> ACK timeout, default 5000",
184
+ "--no-wait fire-and-forget: do not wait for the ACK",
185
+ "--reply <ms> keep listening after the ACK and print the reply envelope(s)",
186
+ "--body-json <json> send structured JSON instead of plain text",
187
+ "--dry-run print the envelope instead of sending it",
188
+ ],
189
+ examples: [
190
+ "pp mesh ls",
191
+ "pp mesh resolve backend",
192
+ 'pp mesh send backend "the build is green"',
193
+ 'pp mesh send 1 3 "heads up: rebooting the box"',
194
+ 'pp mesh send all "standup in 5"',
195
+ "pp mesh send macbook:/Users/me/code/api@api \"ping\" --wait 2000",
196
+ ],
197
+ see: ["send", "status"],
198
+ },
157
199
  {
158
200
  name: "check",
159
201
  aliases: ["validate"],
package/src/mesh.js ADDED
@@ -0,0 +1,224 @@
1
+ import { connect } from "node:net";
2
+ import { randomUUID } from "node:crypto";
3
+ import { homedir } from "node:os";
4
+ import { join } from "node:path";
5
+
6
+ /**
7
+ * Minimal, dependency-free client for the local remote-pi mesh broker.
8
+ *
9
+ * The broker speaks JSON lines over a UNIX socket
10
+ * (`~/.pi/remote/sessions/local/broker.sock`). Three frames are enough for a
11
+ * CLI: an unregistered `list_peers` probe (read-only — no registration, no
12
+ * peer_joined/peer_left broadcast), a `register` handshake, and routed
13
+ * envelopes. Cross-PC delivery rides the leader's relay bridge, so a local
14
+ * peer can address `macbook:/path@name` without pairing anything itself.
15
+ */
16
+
17
+ export const DEFAULT_ACK_TIMEOUT_MS = 5000;
18
+ export const BROADCAST_TARGET = "broadcast";
19
+
20
+ export class MeshError extends Error {
21
+ constructor(message, code = "mesh") {
22
+ super(message);
23
+ this.name = "MeshError";
24
+ this.code = code;
25
+ }
26
+ }
27
+
28
+ /** Absolute path of the local broker socket (`REMOTE_PI_HOME` aware). */
29
+ export function brokerSockPath(env = process.env) {
30
+ const home = env.REMOTE_PI_HOME || homedir();
31
+ return join(home, ".pi", "remote", "sessions", "local", "broker.sock");
32
+ }
33
+
34
+ /** `<pc>:` prefix of a cross-PC address, or null for a local one. */
35
+ export function peerPc(address) {
36
+ if (typeof address !== "string") return null;
37
+ const match = /^([A-Za-z0-9._-]+):\//.exec(address);
38
+ return match ? match[1] : null;
39
+ }
40
+
41
+ /** The address a configured session registers as (`<cwd>@<name>`), or null. */
42
+ export function sessionMeshAddress(session) {
43
+ if (!session || !session.remotePiName) return null;
44
+ if (session.remotePiMode === "off") return null;
45
+ return `${session.cwd}@${session.remotePiName}`;
46
+ }
47
+
48
+ /**
49
+ * Live peer addresses that belong to `address`. The broker appends `#N` when
50
+ * two agents in the same directory ask for the same name, so an exact match is
51
+ * not enough.
52
+ */
53
+ export function livePeersFor(peers, address) {
54
+ if (!address) return [];
55
+ return peers.filter((peer) => peer === address || peer.startsWith(`${address}#`));
56
+ }
57
+
58
+ function attachLineReader(socket, onMessage) {
59
+ let buffer = "";
60
+ socket.setEncoding("utf8");
61
+ socket.on("data", (chunk) => {
62
+ buffer += chunk;
63
+ let index;
64
+ while ((index = buffer.indexOf("\n")) >= 0) {
65
+ const line = buffer.slice(0, index).trim();
66
+ buffer = buffer.slice(index + 1);
67
+ if (!line) continue;
68
+ let message;
69
+ try {
70
+ message = JSON.parse(line);
71
+ } catch {
72
+ continue; // a broken line must not kill the session
73
+ }
74
+ if (message && typeof message === "object") onMessage(message);
75
+ }
76
+ });
77
+ }
78
+
79
+ function connectSocket(sockPath, onError) {
80
+ const socket = connect(sockPath);
81
+ socket.once("error", (error) => {
82
+ const code = error && typeof error === "object" ? error.code : undefined;
83
+ onError(
84
+ new MeshError(
85
+ code === "ENOENT" || code === "ECONNREFUSED"
86
+ ? `no mesh broker at ${sockPath} (start remote-pi inside a pi session, or run "/remote-pi")`
87
+ : `cannot reach mesh broker at ${sockPath}: ${code ?? error.message}`,
88
+ code === "ENOENT" || code === "ECONNREFUSED" ? "no_broker" : "socket",
89
+ ),
90
+ );
91
+ });
92
+ return socket;
93
+ }
94
+
95
+ /**
96
+ * Read-only roster query. Registers nothing and broadcasts nothing, so it is
97
+ * safe to call from any script at any time.
98
+ */
99
+ export function probePeers({ sockPath = brokerSockPath(), timeoutMs = 3000 } = {}) {
100
+ return new Promise((resolve, reject) => {
101
+ let settled = false;
102
+ const finish = (error, value) => {
103
+ if (settled) return;
104
+ settled = true;
105
+ clearTimeout(timer);
106
+ socket.destroy();
107
+ if (error) reject(error);
108
+ else resolve(value);
109
+ };
110
+ const timer = setTimeout(
111
+ () => finish(new MeshError(`no reply from mesh broker at ${sockPath} within ${timeoutMs}ms`, "timeout")),
112
+ timeoutMs,
113
+ );
114
+ const socket = connectSocket(sockPath, (error) => finish(error));
115
+ attachLineReader(socket, (message) => {
116
+ if (message.body && message.body.type === "list_peers_reply") {
117
+ finish(null, Array.isArray(message.body.peers) ? message.body.peers.filter((p) => typeof p === "string") : []);
118
+ }
119
+ });
120
+ socket.write(`${JSON.stringify({ type: "list_peers" })}\n`);
121
+ });
122
+ }
123
+
124
+ /**
125
+ * Join the mesh as an ephemeral peer. Resolves once the broker assigns an
126
+ * address; the returned handle can send envelopes and wait for their ACK.
127
+ */
128
+ export function connectPeer({ sockPath = brokerSockPath(), name = "pp-mesh", cwd = process.cwd(), timeoutMs = 5000 } = {}) {
129
+ return new Promise((resolve, reject) => {
130
+ const pendingAcks = new Map();
131
+ const listeners = new Set();
132
+ let address = null;
133
+ let assignedName = null;
134
+ let settled = false;
135
+
136
+ const socket = connectSocket(sockPath, (error) => {
137
+ if (!settled) {
138
+ settled = true;
139
+ clearTimeout(timer);
140
+ socket.destroy();
141
+ reject(error);
142
+ }
143
+ });
144
+
145
+ const timer = setTimeout(() => {
146
+ if (settled) return;
147
+ settled = true;
148
+ socket.destroy();
149
+ reject(new MeshError(`mesh broker did not acknowledge the registration of "${name}" within ${timeoutMs}ms`, "timeout"));
150
+ }, timeoutMs);
151
+
152
+ attachLineReader(socket, (message) => {
153
+ if (!settled) {
154
+ if (message.type === "register_ack" && typeof message.address_assigned === "string") {
155
+ settled = true;
156
+ clearTimeout(timer);
157
+ address = message.address_assigned;
158
+ assignedName = typeof message.name_assigned === "string" ? message.name_assigned : address;
159
+ resolve({
160
+ socket,
161
+ address,
162
+ name: assignedName,
163
+ onMessage(handler) {
164
+ listeners.add(handler);
165
+ return () => listeners.delete(handler);
166
+ },
167
+ send(to, body, re = null) {
168
+ return sendRaw(socket, address, to, body, re);
169
+ },
170
+ waitAck(id, ms = DEFAULT_ACK_TIMEOUT_MS) {
171
+ return new Promise((done) => {
172
+ const ackTimer = setTimeout(() => {
173
+ pendingAcks.delete(id);
174
+ done({ status: "timeout", id });
175
+ }, ms);
176
+ pendingAcks.set(id, (result) => {
177
+ clearTimeout(ackTimer);
178
+ done(result);
179
+ });
180
+ });
181
+ },
182
+ async sendWithAck(to, body, ms = DEFAULT_ACK_TIMEOUT_MS, re = null) {
183
+ const id = sendRaw(socket, address, to, body, re);
184
+ const result = await this.waitAck(id, ms);
185
+ return { ...result, id };
186
+ },
187
+ close() {
188
+ try {
189
+ socket.end();
190
+ } catch {
191
+ /* already gone */
192
+ }
193
+ },
194
+ });
195
+ return;
196
+ }
197
+ if (message.type !== "peer_joined" && message.type !== "peer_left") {
198
+ settled = true;
199
+ clearTimeout(timer);
200
+ socket.destroy();
201
+ reject(new MeshError(`unexpected frame during registration: ${JSON.stringify(message).slice(0, 120)}`, "protocol"));
202
+ }
203
+ return;
204
+ }
205
+ if (message.body && message.body.type === "ack" && typeof message.re === "string") {
206
+ const waiter = pendingAcks.get(message.re);
207
+ if (waiter) {
208
+ pendingAcks.delete(message.re);
209
+ waiter({ status: message.body.status ?? "received", target: message.body.target, id: message.re });
210
+ }
211
+ return;
212
+ }
213
+ for (const listener of listeners) listener(message);
214
+ });
215
+
216
+ socket.write(`${JSON.stringify({ type: "register", name, cwd })}\n`);
217
+ });
218
+ }
219
+
220
+ function sendRaw(socket, from, to, body, re = null) {
221
+ const id = randomUUID();
222
+ socket.write(`${JSON.stringify({ from, to, id, re, body })}\n`);
223
+ return id;
224
+ }