@bom0792/herdgate 0.9.29 → 0.9.34

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.
Files changed (53) hide show
  1. package/.agents/skills/herdr/SKILL.md +81 -0
  2. package/.agents/skills/herdr/herdr_pi.py +272 -0
  3. package/.agents/skills/herdr/profiles.example.toml +18 -0
  4. package/.agents/skills/herdr-advisor/SKILL.md +12 -0
  5. package/.agents/skills/herdr-committee/SKILL.md +13 -0
  6. package/.agents/skills/herdr-handoff/SKILL.md +19 -0
  7. package/.agents/skills/herdr-help/SKILL.md +14 -0
  8. package/.agents/skills/herdr-plugin/SKILL.md +21 -0
  9. package/DEPLOY.md +106 -120
  10. package/DESIGN.md +9 -4
  11. package/README.md +55 -2
  12. package/bin/herdgate.mjs +12 -2
  13. package/bin/home-tui.mjs +2 -0
  14. package/bin/pi-skills.mjs +99 -0
  15. package/dist-readme.md +9 -2
  16. package/package.json +38 -9
  17. package/plugin/server/e2e.d.mts +2 -2
  18. package/plugin/server/e2e.mjs +51 -32
  19. package/plugin/server/index.mjs +128 -32
  20. package/plugin/server/pi-receipts.d.mts +28 -0
  21. package/plugin/server/pi-receipts.mjs +77 -0
  22. package/plugin/server/pi-worker.d.mts +47 -0
  23. package/plugin/server/pi-worker.mjs +127 -0
  24. package/plugin/server/ssh.mjs +12 -4
  25. package/scripts/bench-mobile-tui.mjs +246 -0
  26. package/scripts/build-host-bundle.sh +14 -8
  27. package/scripts/build-release.sh +47 -0
  28. package/scripts/deploy-vps.sh +5 -78
  29. package/scripts/install-pi-skills.mjs +4 -0
  30. package/src/cloud/gateway.ts +163 -134
  31. package/src/cloud/main.ts +72 -15
  32. package/src/cloud/pairing.ts +7 -2
  33. package/src/cloud/push.ts +54 -0
  34. package/src/cloud/sshd.ts +76 -38
  35. package/src/cloud/util.ts +5 -5
  36. package/src/host/mobile-tui.ts +11 -1
  37. package/src/web/app.js +88 -61
  38. package/src/web/e2e.js +51 -32
  39. package/src/web/sw.js +1 -1
  40. package/templates/cloud/.dockerignore +7 -0
  41. package/templates/cloud/Caddyfile.example +3 -0
  42. package/templates/cloud/Dockerfile +10 -0
  43. package/templates/cloud/README.md +74 -0
  44. package/templates/cloud/compose.env.example +18 -0
  45. package/templates/cloud/compose.yml +41 -0
  46. package/templates/cloud/gitignore.example +4 -0
  47. package/templates/cloud/herdgate-cloud-edge.service +18 -0
  48. package/templates/cloud/herdgate-cloud.service +26 -0
  49. package/tsconfig.cloud.json +11 -0
  50. package/tsconfig.json +18 -0
  51. package/windows/install-cli.mjs +15 -5
  52. package/windows/setup-tui.mjs +1 -0
  53. package/src/web/herdgate-host.zip +0 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bom0792/herdgate",
3
- "version": "0.9.29",
3
+ "version": "0.9.34",
4
4
  "description": "Cloud relay hub for herdr-core: every machine dials out, phones and browsers follow (PWA + SSH leg, E2E payloads).",
5
5
  "type": "module",
6
6
  "engines": {
@@ -12,10 +12,12 @@
12
12
  "edge": "node src/dev/main.ts",
13
13
  "test": "node --test test/*.test.ts",
14
14
  "check": "tsc -p tsconfig.json",
15
+ "build:cloud": "tsc -p tsconfig.cloud.json",
16
+ "build:release": "bash scripts/build-release.sh",
15
17
  "ssh-bridge": "node src/cloud/ssh-bridge.ts",
16
18
  "ssh-tcp-edge": "node src/cloud/ssh-tcp-edge.ts",
17
19
  "mobile-tui": "node src/host/mobile-tui.ts",
18
- "postinstall": "node scripts/patch-ssh2.mjs"
20
+ "postinstall": "node scripts/patch-ssh2.mjs && node scripts/install-pi-skills.mjs"
19
21
  },
20
22
  "dependencies": {
21
23
  "ssh2": "^1.17.0",
@@ -31,15 +33,42 @@
31
33
  "herdgate": "bin/herdgate.mjs"
32
34
  },
33
35
  "files": [
34
- "bin",
35
- "src",
36
- "app-mod",
37
- "plugin",
38
- "scripts",
36
+ "bin/*.mjs",
37
+ ".agents/skills/herdr*/SKILL.md",
38
+ ".agents/skills/herdr/herdr_pi.py",
39
+ ".agents/skills/herdr/profiles.example.toml",
40
+ "src/**/*.ts",
41
+ "src/host/*.mjs",
42
+ "src/web/index.html",
43
+ "src/web/*.css",
44
+ "src/web/*.js",
45
+ "src/web/app.webmanifest",
46
+ "src/web/icons/icon.svg",
47
+ "src/web/icons/icon-192.png",
48
+ "src/web/icons/icon-512.png",
49
+ "app-mod/herdgate/main.js",
50
+ "app-mod/herdgate/mod.json",
51
+ "app-mod/herdgate/herdgate.svg",
52
+ "plugin/herdr-plugin.toml",
53
+ "plugin/server/*.mjs",
54
+ "plugin/server/*.d.mts",
55
+ "scripts/*.mjs",
56
+ "scripts/*.sh",
39
57
  "DEPLOY.md",
40
58
  "DESIGN.md",
41
59
  "dist-readme.md",
42
- "templates",
43
- "windows"
60
+ "templates/herdgate-via.mjs",
61
+ "templates/herdgate-tcp-edge.service",
62
+ "templates/cloud/Caddyfile.example",
63
+ "templates/cloud/Dockerfile",
64
+ "templates/cloud/.dockerignore",
65
+ "templates/cloud/gitignore.example",
66
+ "templates/cloud/README.md",
67
+ "templates/cloud/compose.env.example",
68
+ "templates/cloud/compose.yml",
69
+ "templates/cloud/*.service",
70
+ "tsconfig.json",
71
+ "tsconfig.cloud.json",
72
+ "windows/*.mjs"
44
73
  ]
45
74
  }
@@ -12,7 +12,7 @@ export declare function b64d(s: string): Uint8Array;
12
12
  export declare function utf8e(s: string): Uint8Array;
13
13
  export declare function utf8d(u8: Uint8Array): string;
14
14
  export declare function concat(...parts: Uint8Array[]): Uint8Array;
15
- export declare function fingerprint(pub: Uint8Array): string;
15
+ export declare function fingerprint(pub: Uint8Array): Promise<string>;
16
16
  export declare function generateKeyPair(): Promise<{ jwk: JsonWebKey; pub: Uint8Array }>;
17
17
 
18
18
  export interface NoiseWire {
@@ -25,7 +25,7 @@ export interface NoiseWire {
25
25
  export declare class DeviceChannel {
26
26
  constructor(self: { jwk: JsonWebKey; pub: Uint8Array });
27
27
  begin(): Promise<{ e: string }>;
28
- acceptReply(msg: { e: string; c: string }): Promise<{ c: string }>;
28
+ acceptReply(msg: { e: string; c: string }, expectedHost?: string | null): Promise<{ c: string }>;
29
29
  ready(): boolean;
30
30
  hostFingerprint: string | null;
31
31
  send(obj: unknown): Promise<{ op: string; n: number; c: string }>;
@@ -47,11 +47,15 @@ export function concat(...parts) {
47
47
  return out;
48
48
  }
49
49
 
50
- /** Short human-checkable fingerprint of a static public key (8 bytes, url-safe). */
51
- export function fingerprint(pub) {
50
+ /** Legacy pin matching is used only to upgrade existing browser pins. */
51
+ function legacyFingerprint(pub) {
52
52
  return b64e(pub.slice(0, 8)).replace(/[^A-Za-z0-9]/g, "").toLowerCase().slice(0, 12);
53
53
  }
54
54
 
55
+ export async function fingerprint(pub) {
56
+ return "SHA256:" + b64e(await sha256(pub)).replace(/=+$/, "");
57
+ }
58
+
55
59
  // ---- WebCrypto plumbing ----------------------------------------------------
56
60
 
57
61
  const subtle = globalThis.crypto.subtle;
@@ -90,31 +94,38 @@ export async function generateKeyPair() {
90
94
  class CipherState {
91
95
  k = null;
92
96
  n = 0;
97
+ #tail = Promise.resolve();
93
98
  setKey(k) {
94
99
  this.k = k;
95
100
  }
96
- nonce() {
97
- // 96-bit: 4 zero bytes ‖ BE64(n) — n stays below 2^32 for our lifetimes.
101
+ nonce(n) {
102
+ // 96-bit: 4 zero bytes ‖ BE64(n); sessions are bounded below 2^32.
98
103
  const iv = new Uint8Array(12);
99
- new DataView(iv.buffer).setUint32(8, this.n);
104
+ new DataView(iv.buffer).setUint32(8, n);
100
105
  return iv;
101
106
  }
102
- async encrypt(ad, plaintext) {
103
- if (this.n >= 0xffffffff) throw new Error("e2e: nonce exhausted");
104
- const key = await subtle.importKey("raw", this.k, "AES-GCM", false, ["encrypt"]);
105
- const ct = new Uint8Array(
106
- await subtle.encrypt({ name: "AES-GCM", iv: this.nonce(), additionalData: ad, tagLength: 128 }, key, plaintext),
107
- );
108
- this.n += 1;
109
- return ct;
107
+ #enqueue(operation) {
108
+ const result = this.#tail.then(operation);
109
+ this.#tail = result.catch(() => {});
110
+ return result;
110
111
  }
111
- async decrypt(ad, ciphertext) {
112
- const key = await subtle.importKey("raw", this.k, "AES-GCM", false, ["decrypt"]);
113
- const pt = new Uint8Array(
114
- await subtle.decrypt({ name: "AES-GCM", iv: this.nonce(), additionalData: ad, tagLength: 128 }, key, ciphertext),
115
- );
116
- this.n += 1;
117
- return pt;
112
+ encrypt(ad, plaintext) {
113
+ return this.#enqueue(async () => {
114
+ if (this.n >= 0xffffffff) throw new Error("e2e: nonce exhausted");
115
+ const n = this.n++;
116
+ const key = await subtle.importKey("raw", this.k, "AES-GCM", false, ["encrypt"]);
117
+ const ct = new Uint8Array(await subtle.encrypt({ name: "AES-GCM", iv: this.nonce(n), additionalData: ad, tagLength: 128 }, key, plaintext));
118
+ return { ct, n };
119
+ });
120
+ }
121
+ decrypt(ad, ciphertext, n) {
122
+ return this.#enqueue(async () => {
123
+ if (this.n >= 0xffffffff || (n !== undefined && n !== this.n)) throw new Error("e2e: invalid nonce counter");
124
+ const key = await subtle.importKey("raw", this.k, "AES-GCM", false, ["decrypt"]);
125
+ const pt = new Uint8Array(await subtle.decrypt({ name: "AES-GCM", iv: this.nonce(this.n), additionalData: ad, tagLength: 128 }, key, ciphertext));
126
+ this.n += 1;
127
+ return pt;
128
+ });
118
129
  }
119
130
  }
120
131
 
@@ -151,7 +162,7 @@ class Handshake {
151
162
  }
152
163
  /** The `s` token: transport under the current key, else in the clear (ENC0). */
153
164
  async writeTokenStatic(pubRaw) {
154
- const out = this.cs.k ? await this.cs.encrypt(this.h, pubRaw) : pubRaw;
165
+ const out = this.cs.k ? (await this.cs.encrypt(this.h, pubRaw)).ct : pubRaw;
155
166
  await this.mixHash(out);
156
167
  return out;
157
168
  }
@@ -189,14 +200,18 @@ export class DeviceChannel {
189
200
  return { e: b64e(this.#e.pub) };
190
201
  }
191
202
  /** Feed the host's `{op:"e2e.reply", e, c}`; returns the msg3 payload. */
192
- async acceptReply(msg) {
203
+ async acceptReply(msg, expectedHost = null) {
193
204
  const eHost = b64d(msg.e);
194
205
  if (eHost.length !== PUB_LEN) throw new Error("e2e: bad host ephemeral");
195
206
  await this.#hs.mixHash(eHost);
196
207
  await this.#hs.mixKey(await dh(this.#e.jwk, eHost)); // ee
197
208
  const sHost = await this.#hs.readTokenStatic(b64d(msg.c)); // s
198
209
  if (sHost.length !== PUB_LEN) throw new Error("e2e: bad host static");
199
- this.hostFingerprint = fingerprint(sHost);
210
+ const fp = await fingerprint(sHost);
211
+ if (expectedHost && expectedHost !== fp && (expectedHost.startsWith("SHA256:") || expectedHost !== legacyFingerprint(sHost))) {
212
+ throw Object.assign(new Error("e2e: host key changed"), { code: "host-key-changed" });
213
+ }
214
+ this.hostFingerprint = fp;
200
215
  await this.#hs.mixKey(await dh(this.#e.jwk, sHost)); // es (e_dev × s_host)
201
216
  const c = await this.#hs.writeTokenStatic(this.#self.pub); // s_dev
202
217
  await this.#hs.mixKey(await dh(this.#self.jwk, eHost)); // se (e_host × s_dev)
@@ -210,12 +225,11 @@ export class DeviceChannel {
210
225
  return Boolean(this.sendCs && this.recvCs);
211
226
  }
212
227
  async send(obj) {
213
- const ct = await this.sendCs.encrypt(this.#hs.h, utf8e(JSON.stringify(obj)));
214
- return { op: "e2e", n: this.sendCs.n - 1, c: b64e(ct) };
228
+ const { ct, n } = await this.sendCs.encrypt(this.#hs.h, utf8e(JSON.stringify(obj)));
229
+ return { op: "e2e", n, c: b64e(ct) };
215
230
  }
216
231
  async recv(msg) {
217
- const pt = await this.recvCs.decrypt(this.#hs.h, b64d(msg.c));
218
- return JSON.parse(utf8d(pt));
232
+ return receive(this.recvCs, this.#hs.h, msg);
219
233
  }
220
234
  }
221
235
 
@@ -247,7 +261,7 @@ export class HostChannel {
247
261
  async acceptFinish(msg) {
248
262
  const sDev = await this.#hs.readTokenStatic(b64d(msg.c)); // s_dev
249
263
  if (sDev.length !== PUB_LEN) throw new Error("e2e: bad device static");
250
- this.deviceFingerprint = fingerprint(sDev);
264
+ this.deviceFingerprint = await fingerprint(sDev);
251
265
  await this.#hs.mixKey(await dh(this.#e.jwk, sDev)); // se (e_host × s_dev)
252
266
  const [c1, c2] = await this.#hs.split();
253
267
  this.recvCs = c1; // device → host (c1 encrypts initiator→responder)
@@ -258,11 +272,16 @@ export class HostChannel {
258
272
  return Boolean(this.sendCs && this.recvCs);
259
273
  }
260
274
  async send(obj) {
261
- const ct = await this.sendCs.encrypt(this.#hs.h, utf8e(JSON.stringify(obj)));
262
- return { op: "e2e", n: this.sendCs.n - 1, c: b64e(ct) };
275
+ const { ct, n } = await this.sendCs.encrypt(this.#hs.h, utf8e(JSON.stringify(obj)));
276
+ return { op: "e2e", n, c: b64e(ct) };
263
277
  }
264
278
  async recv(msg) {
265
- const pt = await this.recvCs.decrypt(this.#hs.h, b64d(msg.c));
266
- return JSON.parse(utf8d(pt));
279
+ return receive(this.recvCs, this.#hs.h, msg);
267
280
  }
268
281
  }
282
+
283
+ async function receive(cipher, handshakeHash, msg) {
284
+ if (!Number.isInteger(msg.n) || msg.n < 0 || msg.n >= 0xffffffff) throw new Error("e2e: invalid nonce counter");
285
+ const plaintext = await cipher.decrypt(handshakeHash, b64d(msg.c), msg.n);
286
+ return JSON.parse(utf8d(plaintext));
287
+ }
@@ -7,12 +7,15 @@
7
7
  */
8
8
 
9
9
  import { spawn } from "node:child_process";
10
+ import { randomUUID } from "node:crypto";
10
11
  import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
11
12
  import { join, dirname } from "node:path";
12
13
  import { hostname, homedir } from "node:os";
13
14
  import { fileURLToPath } from "node:url";
14
15
  import { dirs, readConfig, writeConfig, readState, writeState, herdrSnapshot, summarize, herdrPanes, herdrRead } from "./common.mjs";
15
16
  import { createSshBridge } from "./ssh.mjs";
17
+ import { findReceipt, journalBase as receiptJournalBase, publicReceipt } from "./pi-receipts.mjs";
18
+ import { JOB_ID, MAX_PENDING, MAX_PROMPT, appendJob, jobsFile, publicJob, queueDepth, readHeartbeat, readJobs, workerBase } from "./pi-worker.mjs";
16
19
  import { registerPublisher } from "./publisher-tui-lifecycle.mjs";
17
20
  import { HostChannel, b64d, b64e, fingerprint, generateKeyPair } from "./e2e.mjs";
18
21
 
@@ -196,45 +199,48 @@ async function publisherLoop() {
196
199
  // A device that has not completed the handshake keeps working in the clear —
197
200
  // the plaintext path stays the compat fallback.
198
201
  const e2eKeyPath = D.stateDir ? join(D.stateDir, "e2e-host.json") : "";
199
- let e2eSelf = null;
200
- const e2eSelfKey = async () => {
201
- if (e2eSelf) return e2eSelf;
202
+ let e2eIdentity;
203
+ const e2eSelfKey = () => e2eIdentity ??= (async () => {
202
204
  try {
203
205
  const j = JSON.parse(readFileSync(e2eKeyPath, "utf8"));
204
- e2eSelf = { jwk: j.jwk, pub: b64d(j.pub) };
205
- return e2eSelf;
206
- } catch {
207
- /* mint a fresh identity below */
208
- }
209
- e2eSelf = await generateKeyPair();
210
- try {
211
- mkdirSync(dirname(e2eKeyPath), { recursive: true });
212
- writeFileSync(e2eKeyPath, JSON.stringify({ jwk: e2eSelf.jwk, pub: b64e(e2eSelf.pub) }), { mode: 0o600 });
206
+ return { jwk: j.jwk, pub: b64d(j.pub) };
213
207
  } catch (e) {
214
- log(`e2e: could not persist host key (${e instanceof Error ? e.message : String(e)})`);
208
+ if (e.code !== "ENOENT") throw new Error("cannot load existing E2E host identity");
215
209
  }
216
- return e2eSelf;
217
- };
210
+ const key = await generateKeyPair();
211
+ mkdirSync(dirname(e2eKeyPath), { recursive: true, mode: 0o700 });
212
+ writeFileSync(e2eKeyPath, JSON.stringify({ jwk: key.jwk, pub: b64e(key.pub) }), { mode: 0o600, flag: "wx" });
213
+ return key;
214
+ })();
218
215
  const e2eSessions = new Map();
216
+ const acceptingFinish = new WeakSet();
219
217
  /** Per-device last-call times for the subprocess-backed term.* ops (1/s each). */
220
218
  const termThrottle = new Map();
221
219
  /** null = not an e2e payload; {reply} = handshake answer to send; {inner} = decrypted device payload. */
222
- const e2eOnDevice = async (device, payload) => {
220
+ const e2eOnDevice = async (ws, device, payload) => {
223
221
  if (payload && typeof payload === "object" && typeof payload.op === "string" && payload.op.startsWith("e2e")) log(`e2e: op ${payload.op} from ${device}`);
224
222
  if (!payload || typeof payload !== "object") return null;
225
223
  if (payload.op === "e2e.init") {
226
224
  const ch = new HostChannel(await e2eSelfKey());
225
+ if (wsRef !== ws || ws.readyState !== 1 || !devices.some(d => d.id === device)) return { reply: null };
227
226
  e2eSessions.set(device, ch);
228
- return { reply: { op: "e2e.reply", ...(await ch.acceptInit(payload)) } };
227
+ const reply = await ch.acceptInit(payload);
228
+ return e2eSessions.get(device) === ch ? { reply: { op: "e2e.reply", ...reply } } : { reply: null };
229
229
  }
230
230
  if (payload.op === "e2e.finish") {
231
231
  const ch = e2eSessions.get(device);
232
- if (!ch) return { reply: { op: "error", code: "e2e", message: "no handshake in progress" } };
233
- await ch.acceptFinish(payload);
234
- log(`e2e: session up with ${device} (host fp ${fingerprint((await e2eSelfKey()).pub)})`);
235
- // The ack is the start signal: the device encrypts nothing before it, so no
236
- // transport frame can race the handshake's last step and desync the counters.
237
- return { reply: { op: "e2e.ready" } };
232
+ if (!ch || ch.ready() || acceptingFinish.has(ch)) return { reply: null };
233
+ acceptingFinish.add(ch);
234
+ try {
235
+ const fp = await fingerprint((await e2eSelfKey()).pub);
236
+ await ch.acceptFinish(payload);
237
+ if (e2eSessions.get(device) === ch && wsRef === ws && ws.readyState === 1) {
238
+ // Queue the ack before allowing the first ciphertext to be sent.
239
+ ws.send(JSON.stringify({ v: 1, t: "frame", device, payload: { op: "e2e.ready" } }));
240
+ log(`e2e: session up with ${device} (host fp ${fp})`);
241
+ }
242
+ return { reply: null };
243
+ } finally { acceptingFinish.delete(ch); }
238
244
  }
239
245
  if (payload.op === "e2e") {
240
246
  const ch = e2eSessions.get(device);
@@ -244,6 +250,7 @@ async function publisherLoop() {
244
250
  } catch {
245
251
  // A decrypt failure means the counters can never resync: drop the session and
246
252
  // make the device renegotiate.
253
+ if (e2eSessions.get(device) !== ch) return { reply: null };
247
254
  e2eSessions.delete(device);
248
255
  log(`e2e: dropped session with ${device} (decrypt failed — renegotiate)`);
249
256
  return { reply: { op: "error", code: "e2e", message: "session dropped — renegotiate" } };
@@ -251,10 +258,15 @@ async function publisherLoop() {
251
258
  }
252
259
  return null;
253
260
  };
254
- /** Encrypt for this device when a session exists; passthrough otherwise. */
255
- const e2eToDevice = async (device, payload) => {
261
+ /** Encrypt for this device when a session exists; passthrough for legacy clients. */
262
+ const sendPayload = async (ws, device, payload) => {
263
+ if (wsRef !== ws || ws.readyState !== 1 || !devices.some(d => d.id === device)) return;
256
264
  const ch = e2eSessions.get(device);
257
- return ch?.ready() ? ch.send(payload) : payload;
265
+ if (acceptingFinish.has(ch)) return;
266
+ const wire = ch?.ready() ? await ch.send(payload) : payload;
267
+ if (wsRef === ws && ws.readyState === 1 && e2eSessions.get(device) === ch) {
268
+ ws.send(JSON.stringify({ v: 1, t: "frame", device, payload: wire }));
269
+ }
258
270
  };
259
271
 
260
272
  const ssh = createSshBridge({
@@ -278,7 +290,7 @@ async function publisherLoop() {
278
290
  const payload = await snapshotPayload();
279
291
  if (!payload) return;
280
292
  for (const d of devices) {
281
- ws.send(JSON.stringify({ v: 1, t: "frame", device: d.id, payload: await e2eToDevice(d.id, payload) }));
293
+ await sendPayload(ws, d.id, payload);
282
294
  }
283
295
  };
284
296
 
@@ -339,7 +351,10 @@ async function publisherLoop() {
339
351
  }
340
352
  if (m.t === "room.update") {
341
353
  const next = m.devices ?? [];
342
- for (const d of devices) if (!next.some((n) => n.id === d.id && n.scope === d.scope)) ssh.dropDevice(d.id);
354
+ for (const d of devices) if (!next.some((n) => n.id === d.id && n.scope === d.scope)) {
355
+ ssh.dropDevice(d.id);
356
+ e2eSessions.delete(d.id);
357
+ }
343
358
  devices = next;
344
359
  void publish(ws);
345
360
  return;
@@ -352,7 +367,7 @@ async function publisherLoop() {
352
367
  ssh.handle(m.device, m.payload);
353
368
  return;
354
369
  }
355
- const unwrapped = await e2eOnDevice(m.device, m.payload);
370
+ const unwrapped = await e2eOnDevice(ws, m.device, m.payload);
356
371
  if (unwrapped) {
357
372
  if (unwrapped.reply !== null && unwrapped.reply !== undefined) {
358
373
  ws.send(JSON.stringify({ v: 1, t: "frame", device: m.device, payload: unwrapped.reply }));
@@ -361,10 +376,90 @@ async function publisherLoop() {
361
376
  }
362
377
  const payload = unwrapped?.inner ?? m.payload;
363
378
  const op = payload && typeof payload === "object" ? payload.op : undefined;
364
- const replyTo = async (out) => {
365
- ws.send(JSON.stringify({ v: 1, t: "frame", device: m.device, payload: await e2eToDevice(m.device, out) }));
366
- };
379
+ const replyTo = (out) => sendPayload(ws, m.device, out).catch(e => log(`payload send failed: ${e.message}`));
367
380
  if (op === "ping") return void replyTo({ op: "pong", n: payload.n ?? null, at: new Date().toISOString() });
381
+ if (op === "receipt.get") {
382
+ // Experimental (opt-in HERDGATE_PI_RECEIPTS=1): answer from the local Pi
383
+ // receipt journal written by the experiments/pi-receipt observer.
384
+ // Metadata only — the observer itself never opens a socket.
385
+ const id = typeof payload.id === "string" ? payload.id : "";
386
+ const enabled = process.env.HERDGATE_PI_RECEIPTS === "1";
387
+ const entry = enabled ? findReceipt(receiptJournalBase(), id) : null;
388
+ log(`receipts: ${m.device} queried ${id || "?"} -> ${entry ? entry.status : "unknown"}`);
389
+ return void replyTo({ op: "receipt.result", id: id || null,
390
+ ...publicReceipt(entry), ...(enabled ? {} : { reason: "pi_receipts_disabled" }) });
391
+ }
392
+ if (op === "worker.health") {
393
+ // Experimental (opt-in HERDGATE_PI_WORKER=1): liveness for the owner — queue
394
+ // depth plus the last heartbeat written by the scheduler/worker experiment.
395
+ // Metadata only; read scope is enough; missing heartbeat is reported as null.
396
+ const enabled = process.env.HERDGATE_PI_WORKER === "1";
397
+ let queued = null;
398
+ let running = null;
399
+ let beat = null;
400
+ if (enabled) {
401
+ try { const depth = queueDepth(readJobs(jobsFile(workerBase()))); queued = depth.queued; running = depth.running; }
402
+ catch { /* unreadable queue -> null, fail closed */ }
403
+ beat = readHeartbeat(workerBase());
404
+ }
405
+ const age = beat ? Math.max(0, Math.round((Date.now() - beat.ts) / 1000)) : null;
406
+ log(`worker: ${m.device} health -> queued ${queued ?? "?"} running ${running ?? "?"} heartbeat ${beat ? `${age}s ago` : "none"}`);
407
+ return void replyTo({ op: "worker.health.result", enabled,
408
+ ...(enabled
409
+ ? { queued, running, heartbeat: beat ? { ts: beat.ts, source: beat.source, ageSeconds: age } : null }
410
+ : { reason: "pi_worker_disabled" }) });
411
+ }
412
+ if (op === "worker.submit" || op === "worker.status") {
413
+ // Experimental (opt-in HERDGATE_PI_WORKER=1): admission to the local Pi worker
414
+ // queue (plugin/server/pi-worker.mjs). The publisher never runs Pi itself — a
415
+ // separately started experiments/pi-worker drains the queue and journals receipts.
416
+ // worker.submit carries a prompt, so it is a control operation (act scope only).
417
+ const enabled = process.env.HERDGATE_PI_WORKER === "1";
418
+ const file = jobsFile(workerBase());
419
+ const id = typeof payload.id === "string" && JOB_ID.test(payload.id) ? payload.id : "";
420
+ if (op === "worker.status") {
421
+ let job = null;
422
+ if (enabled && id) {
423
+ try { job = readJobs(file).get(id) ?? null; } catch { job = null; }
424
+ }
425
+ log(`worker: ${m.device} status ${id || "?"} -> ${job ? job.state : "unknown"}`);
426
+ return void replyTo({ op: "worker.status.result", id: id || null, ...publicJob(job),
427
+ ...(enabled ? {} : { reason: "pi_worker_disabled" }) });
428
+ }
429
+ if (!enabled) {
430
+ return void replyTo({ op: "error", code: "pi_worker_disabled", message: "the Pi worker queue is not enabled on this host" });
431
+ }
432
+ if (devices.find(d => d.id === m.device)?.scope !== "act") {
433
+ return void replyTo({ op: "error", code: "requires-act", message: "worker.submit needs an act device" });
434
+ }
435
+ const prompt = typeof payload.prompt === "string" ? payload.prompt : "";
436
+ if (!prompt.trim() || prompt.length > MAX_PROMPT) {
437
+ return void replyTo({ op: "error", code: "bad-prompt", message: `worker.submit needs a prompt of 1..${MAX_PROMPT} chars` });
438
+ }
439
+ let jobs;
440
+ try { jobs = readJobs(file); }
441
+ catch (e) {
442
+ return void replyTo({ op: "error", code: "worker-queue", message: `queue unreadable: ${e instanceof Error ? e.message : String(e)}` });
443
+ }
444
+ const existing = id ? jobs.get(id) : undefined;
445
+ const settled = !existing && id ? findReceipt(receiptJournalBase(), id) : null;
446
+ if (existing || settled) {
447
+ const state = existing ? existing.state : String(settled?.status);
448
+ log(`worker: ${m.device} resubmitted ${id} -> ${state} (duplicate)`);
449
+ return void replyTo({ op: "worker.submitted", id, state, duplicate: true });
450
+ }
451
+ const pending = [...jobs.values()].filter(j => j.state === "queued" || j.state === "running").length;
452
+ if (pending >= MAX_PENDING) {
453
+ return void replyTo({ op: "error", code: "queue-full", message: `worker queue is full (${MAX_PENDING} pending)` });
454
+ }
455
+ const jobId = id || randomUUID();
456
+ try { appendJob(file, { v: 1, id: jobId, prompt, ts: Date.now(), state: "queued" }); }
457
+ catch (e) {
458
+ return void replyTo({ op: "error", code: "worker-queue", message: `queue append failed: ${e instanceof Error ? e.message : String(e)}` });
459
+ }
460
+ log(`worker: ${m.device} submitted ${jobId} (${prompt.length} chars)`);
461
+ return void replyTo({ op: "worker.submitted", id: jobId, state: "queued", duplicate: false });
462
+ }
368
463
  if (op === "view") {
369
464
  // Answer this device now, even if the view has not changed since the last push.
370
465
  lastSig = "";
@@ -431,6 +526,7 @@ async function publisherLoop() {
431
526
  if (timer) clearInterval(timer);
432
527
  timer = null;
433
528
  ssh.closeAll();
529
+ e2eSessions.clear();
434
530
  devices = [];
435
531
  const wait = Math.min(30_000, backoff) + Math.random() * 500;
436
532
  backoff *= 2;
@@ -0,0 +1,28 @@
1
+ export interface JournalEntry {
2
+ v?: number;
3
+ id: string;
4
+ status: string;
5
+ reason?: string;
6
+ ts?: number;
7
+ sessionId?: string;
8
+ paneId?: string;
9
+ requestEntryId?: string;
10
+ responseEntryId?: string;
11
+ runtime?: string;
12
+ [key: string]: unknown;
13
+ }
14
+
15
+ export interface PublicReceipt {
16
+ id?: string;
17
+ status: string;
18
+ reason?: string;
19
+ requestEntryId?: string;
20
+ responseEntryId?: string;
21
+ }
22
+
23
+ export function journalBase(env?: Record<string, string | undefined>): string;
24
+ export function scopeFor(cwd: string): string;
25
+ export function validEntry(entry: unknown): JournalEntry | null;
26
+ export function readJournal(dir: string): JournalEntry[];
27
+ export function findReceipt(base: string, id: string): JournalEntry | null;
28
+ export function publicReceipt(entry: JournalEntry | null): PublicReceipt;
@@ -0,0 +1,77 @@
1
+ // Shared reader for the experimental Pi receipt journal (see experiments/pi-receipt).
2
+ // The observer writes; the publisher may answer receipt.get frames from paired
3
+ // devices when HERDGATE_PI_RECEIPTS=1. Read-only, bounded, no network access here.
4
+ import { createHash } from 'node:crypto';
5
+ import { homedir } from 'node:os';
6
+ import { join } from 'node:path';
7
+ import { readFileSync, readdirSync } from 'node:fs';
8
+
9
+ export const RECEIPT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
10
+ const RECEIPTS = 'receipts.jsonl';
11
+
12
+ /** Base directory holding one hashed sub-directory per Pi workspace. */
13
+ export function journalBase(env = process.env) {
14
+ const override = env.HERDGATE_PI_RECEIPT_DIR;
15
+ if (override) return override;
16
+ return join(env.XDG_STATE_HOME || join(homedir(), '.local', 'state'), 'herdgate', 'pi-receipts');
17
+ }
18
+
19
+ export function scopeFor(cwd) {
20
+ return createHash('sha256').update(cwd).digest('hex').slice(0, 16);
21
+ }
22
+
23
+ export function validEntry(entry) {
24
+ return validEntryShape(entry) ? entry : null;
25
+ }
26
+
27
+ function validEntryShape(entry) {
28
+ return Boolean(entry && entry.v === 1 && RECEIPT_ID.test(entry.id ?? '')
29
+ && ['replied', 'failed', 'canceled', 'unknown'].includes(entry.status)
30
+ && typeof entry.sessionId === 'string' && typeof entry.ts === 'number'
31
+ && ['reason', 'requestEntryId', 'responseEntryId', 'paneId'].every(key => entry[key] === undefined || typeof entry[key] === 'string'));
32
+ }
33
+
34
+ /** Parse a journal file; tolerate a torn tail and skip corrupt lines. */
35
+ export function readJournal(file) {
36
+ let raw;
37
+ try { raw = readFileSync(file, 'utf8'); }
38
+ catch (error) { if (error.code === 'ENOENT') return []; throw error; }
39
+ const lines = raw.split('\n');
40
+ lines.pop(); // the empty tail; a torn final line without \n drops with it
41
+ const entries = [];
42
+ for (const line of lines) {
43
+ try {
44
+ const entry = JSON.parse(line);
45
+ if (validEntry(entry)) entries.push(entry);
46
+ } catch { /* skip */ }
47
+ }
48
+ return entries;
49
+ }
50
+
51
+ /**
52
+ * Find the newest receipt for a request ID across workspace journals.
53
+ * Lookup by exact UUID only — there is no enumeration. Returns null when the
54
+ * journals are unreadable or the ID is unknown; callers fail closed.
55
+ */
56
+ export function findReceipt(base, id) {
57
+ if (!RECEIPT_ID.test(id ?? '')) return null;
58
+ try {
59
+ let found = null;
60
+ for (const name of readdirSync(base)) {
61
+ if (!/^[0-9a-f]{16}$/.test(name)) continue;
62
+ for (const entry of readJournal(join(base, name, RECEIPTS))) {
63
+ if (entry.id === id && (!found || entry.ts >= found.ts)) found = entry;
64
+ }
65
+ }
66
+ return found;
67
+ } catch {
68
+ return null;
69
+ }
70
+ }
71
+
72
+ /** The public answer for a device: journal internals stay on the host. */
73
+ export function publicReceipt(entry) {
74
+ if (!entry) return { status: 'unknown', reason: 'not_retained_in_runtime' };
75
+ const { v, ts, sessionId, paneId, ...rest } = entry;
76
+ return rest;
77
+ }
@@ -0,0 +1,47 @@
1
+ export type JobState = 'queued' | 'running' | 'replied' | 'failed' | 'canceled' | 'unknown';
2
+
3
+ export interface JobRecord {
4
+ v: 1;
5
+ id: string;
6
+ prompt: string;
7
+ ts: number;
8
+ state: JobState;
9
+ sessionId?: string;
10
+ reason?: string;
11
+ requestEntryId?: string;
12
+ responseEntryId?: string;
13
+ }
14
+
15
+ export interface PublicJob {
16
+ id?: string;
17
+ state: JobState;
18
+ ts?: number;
19
+ reason?: string;
20
+ sessionId?: string;
21
+ requestEntryId?: string;
22
+ responseEntryId?: string;
23
+ }
24
+
25
+ export const JOB_ID: RegExp;
26
+ export const MAX_PROMPT: number;
27
+ export const MAX_PENDING: number;
28
+ /** Oldest Pi release the experiments are verified against (floor, not a pin). */
29
+ export const MIN_PI_VERSION: string;
30
+ export function versionAtLeast(version: string, min?: string): boolean;
31
+ export function workerBase(env?: Record<string, string | undefined>): string;
32
+ export function jobsFile(base: string): string;
33
+ export function validJob(job: unknown): JobRecord | null;
34
+ export function readJobs(file: string): Map<string, JobRecord>;
35
+ export function appendJob(file: string, job: JobRecord): void;
36
+ export function publicJob(job: JobRecord | null): PublicJob;
37
+ export function queueDepth(jobs: Map<string, JobRecord>): { queued: number; running: number };
38
+ export function scheduledRunId(scheduleId: string, bucket: number): string;
39
+ export interface Heartbeat {
40
+ v: 1;
41
+ ts: number;
42
+ source: string;
43
+ [key: string]: unknown;
44
+ }
45
+ export function heartbeatPath(base: string): string;
46
+ export function writeHeartbeat(base: string, entry: Heartbeat): void;
47
+ export function readHeartbeat(base: string): Heartbeat | null;