@bom0792/herdgate 0.9.37 → 0.9.39
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/.agents/skills/herdr/SKILL.md +65 -0
- package/DESIGN.md +28 -0
- package/README.md +70 -1
- package/package.json +2 -1
- package/plugin/herdr-plugin.toml +18 -1
- package/plugin/server/attachments.mjs +184 -0
- package/plugin/server/git-safe.mjs +126 -0
- package/plugin/server/index.mjs +332 -9
- package/plugin/server/mobile-tui-core.mjs +141 -45
- package/plugin/server/mobile-tui-stream.mjs +258 -1
- package/plugin/server/pi-receipt-gc.mjs +183 -0
- package/plugin/server/pi-receipt-search.mjs +217 -0
- package/plugin/server/pi-receipts.mjs +121 -13
- package/plugin/server/pi-transcript.mjs +217 -0
- package/plugin/server/pi-usage.mjs +84 -0
- package/plugin/server/pi-wake.mjs +319 -0
- package/plugin/server/pi-worker.mjs +16 -3
- package/plugin/server/port-attr.mjs +172 -0
- package/plugin/server/publish-tui.mjs +7 -0
- package/plugin/server/sysmon.mjs +212 -0
- package/plugin/server/wake-event.mjs +255 -0
- package/src/agent/index.ts +4 -2
- package/src/agent/qr.ts +70 -0
- package/src/cloud/gateway.ts +5 -1
- package/src/host/main.ts +14 -1
- package/src/web/app.css +356 -0
- package/src/web/app.js +1395 -14
- package/src/web/index.html +1 -0
- package/windows/npm-update.mjs +261 -11
- package/windows/update-policy.mjs +98 -0
|
@@ -1,15 +1,13 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
// Subset of the Core API for TUI panes. Input requires explicit local opt-in.
|
|
3
|
-
import { execFile } from "node:child_process";
|
|
4
3
|
import { createHash } from "node:crypto";
|
|
5
4
|
import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
|
|
6
5
|
import { open as openFile } from "node:fs/promises";
|
|
7
6
|
import { hostname, homedir } from "node:os";
|
|
8
7
|
import { dirname, join } from "node:path";
|
|
9
|
-
import {
|
|
10
|
-
import { openTerminal, validDimension } from "./mobile-tui-stream.mjs";
|
|
8
|
+
import { stripVTControlCharacters } from "node:util";
|
|
9
|
+
import { cksum, openShellManager, openTerminal, PaneLiveInputQueue, validDimension } from "./mobile-tui-stream.mjs";
|
|
11
10
|
|
|
12
|
-
const invoke = promisify(execFile);
|
|
13
11
|
const herdr = process.env.HERDR_BIN_PATH || join(homedir(), ".local/bin/herdr");
|
|
14
12
|
const name = process.env.HERDGATE_HOST_NAME || "home-tui-mobile";
|
|
15
13
|
const digest = (text) => createHash("sha256").update(text).digest("hex");
|
|
@@ -51,7 +49,17 @@ const pollMs = Math.max(250, Number.parseInt(process.env.HERDGATE_TUI_POLL_MS ??
|
|
|
51
49
|
const startedAt = Date.now();
|
|
52
50
|
let cache;
|
|
53
51
|
let cacheUntil = 0;
|
|
54
|
-
|
|
52
|
+
// One persistent /bin/sh speaks for every Herdr call: each request is framed by a unique
|
|
53
|
+
// marker, the shell is probed (`true`) before it counts as alive, and one channel failure
|
|
54
|
+
// kills the whole generation — the written request is never retried, later requests fall
|
|
55
|
+
// back to one exec per command, and only an explicit reinit() opens the next generation.
|
|
56
|
+
const shells = openShellManager();
|
|
57
|
+
const shellQuote = (word) => `'${String(word).replace(/'/g, "'\\''")}'`;
|
|
58
|
+
const run = async (args) => {
|
|
59
|
+
const { stdout, code } = await shells.execute([herdr, ...args].map(shellQuote).join(" "));
|
|
60
|
+
if (code !== 0) throw Object.assign(new Error(`herdr ${args[0]} exited ${code}`), { definitive: true });
|
|
61
|
+
return stdout.toString("utf8");
|
|
62
|
+
};
|
|
55
63
|
|
|
56
64
|
async function panes() {
|
|
57
65
|
if (cache && Date.now() < cacheUntil) return cache;
|
|
@@ -60,9 +68,9 @@ async function panes() {
|
|
|
60
68
|
cache = parsed.result.panes.filter((p) => typeof p?.pane_id === "string" && /^[a-zA-Z0-9_:.-]{1,128}$/.test(p.pane_id) && !p.pane_id.startsWith("-"))
|
|
61
69
|
.slice(0, 180).map((p) => {
|
|
62
70
|
let title = clip(p.terminal_title_stripped || p.terminal_title || p.pane_id, 120);
|
|
63
|
-
// Herdr's per-pane agent state feeds the core's own status
|
|
64
|
-
|
|
65
|
-
const
|
|
71
|
+
// Herdr's per-pane agent state feeds the core's own status word (a 7501 record
|
|
72
|
+
// shape: an object with a state, never a bare string).
|
|
73
|
+
const status = p.agent_status === "working" ? { state: "working" } : null;
|
|
66
74
|
const ws = typeof p.workspace_id === "string" && /^[a-zA-Z0-9_:.-]{1,128}$/.test(p.workspace_id) ? p.workspace_id : null;
|
|
67
75
|
const tab = typeof p.tab_id === "string" && /^[a-zA-Z0-9_:.-]{1,128}$/.test(p.tab_id) ? p.tab_id : null;
|
|
68
76
|
// The desktop app seats terminals by these labels; ids stay stable per workspace/tab.
|
|
@@ -70,7 +78,7 @@ async function panes() {
|
|
|
70
78
|
return { id: p.pane_id, workspace: ws, tab, target: typeof p.terminal_id === "string" && /^term_[a-zA-Z0-9]{1,96}$/.test(p.terminal_id) ? p.terminal_id : null, terminal: {
|
|
71
79
|
address: "t" + digest(p.pane_id).slice(0, 12), title, name: null, argv: [], cwd: clip(p.cwd, 512),
|
|
72
80
|
state: "live", created_ms: 0, screen: "inexact", cols: 80, rows: 24,
|
|
73
|
-
labels, turn: 0, status,
|
|
81
|
+
labels, turn: 0, status,
|
|
74
82
|
} };
|
|
75
83
|
});
|
|
76
84
|
cacheUntil = Date.now() + 1_000;
|
|
@@ -139,13 +147,20 @@ function layoutTree(items, nodeId) {
|
|
|
139
147
|
|
|
140
148
|
const blockOf = (it) => ({ id: "p" + digest("pane:" + it.pane.id).slice(0, 30), type: "block", content: { terminal: it.pane.terminal.address } });
|
|
141
149
|
|
|
142
|
-
/** Terminal records as the viewers list them: panes with their on-screen geometry.
|
|
150
|
+
/** Terminal records as the viewers list them: panes with their on-screen geometry.
|
|
151
|
+
* Agent panes also carry their program (π) in name/argv — the app's programs table
|
|
152
|
+
* matches argv, so its agents mod and icons light up for them. */
|
|
143
153
|
async function terminalRecords() {
|
|
144
154
|
const rects = await paneRects();
|
|
145
|
-
|
|
155
|
+
const out = [];
|
|
156
|
+
for (const { id, terminal } of await panes()) {
|
|
146
157
|
const rect = rects.get(id);
|
|
147
|
-
|
|
148
|
-
|
|
158
|
+
let record = rect ? { ...terminal, cols: Math.max(2, Math.min(1000, rect.width)), rows: Math.max(2, Math.min(1000, rect.height)) } : { ...terminal };
|
|
159
|
+
const info = await agentInfo(id);
|
|
160
|
+
if (info.agent) record = { ...record, name: info.agent, argv: [info.agent] };
|
|
161
|
+
out.push(record);
|
|
162
|
+
}
|
|
163
|
+
return out;
|
|
149
164
|
}
|
|
150
165
|
|
|
151
166
|
/** Seating changes (workspace/tab/pane set) are what change the layout doc. */
|
|
@@ -155,7 +170,7 @@ function docFingerprint(records) {
|
|
|
155
170
|
|
|
156
171
|
/** What a viewer must hear about between polls: titles, folders, seating, life. */
|
|
157
172
|
function seenFingerprint(records) {
|
|
158
|
-
return new Map(records.map((t) => [t.address, [t.title, t.cwd, t.labels["herdr.space"] ?? null, t.labels["herdr.tab"] ?? null, t.status
|
|
173
|
+
return new Map(records.map((t) => [t.address, [t.title, t.cwd, t.labels["herdr.space"] ?? null, t.labels["herdr.tab"] ?? null, t.status?.state ?? null]]));
|
|
159
174
|
}
|
|
160
175
|
|
|
161
176
|
function clip(x, n) { return typeof x === "string" ? x.slice(0, n) : ""; }
|
|
@@ -257,18 +272,26 @@ function wrapFor(width, text) {
|
|
|
257
272
|
return out.join("\r\n");
|
|
258
273
|
}
|
|
259
274
|
|
|
260
|
-
const sessionCache = new Map(); // pane_id → { session, until } — pane get is a per-read cost otherwise
|
|
261
|
-
async function
|
|
262
|
-
const cached = sessionCache.get(
|
|
263
|
-
if (cached && Date.now() < cached.until) return cached
|
|
275
|
+
const sessionCache = new Map(); // pane_id → { session, agent, until } — pane get is a per-read cost otherwise
|
|
276
|
+
async function agentInfo(paneId) {
|
|
277
|
+
const cached = sessionCache.get(paneId);
|
|
278
|
+
if (cached && Date.now() < cached.until) return cached;
|
|
264
279
|
let session = null;
|
|
280
|
+
let agent = null;
|
|
265
281
|
try {
|
|
266
|
-
const parsed = JSON.parse(await run(["pane", "get",
|
|
267
|
-
const
|
|
282
|
+
const parsed = JSON.parse(await run(["pane", "get", paneId]));
|
|
283
|
+
const pane = parsed?.result?.pane;
|
|
284
|
+
const value = pane?.agent_session?.value;
|
|
268
285
|
if (typeof value === "string" && value.endsWith(".jsonl") && value.startsWith(homedir() + "/")) session = value;
|
|
286
|
+
if (typeof pane?.agent === "string" && pane.agent) agent = clip(pane.agent, 32);
|
|
269
287
|
} catch { /* a pane without an agent session simply has no transcript */ }
|
|
270
|
-
|
|
271
|
-
|
|
288
|
+
const info = { session, agent, until: Date.now() + 30_000 };
|
|
289
|
+
sessionCache.set(paneId, info);
|
|
290
|
+
return info;
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
async function agentSession(hit) {
|
|
294
|
+
return (await agentInfo(hit.id)).session;
|
|
272
295
|
}
|
|
273
296
|
|
|
274
297
|
/** The pane's recent chat as structured blocks — the history that lives inside the agent
|
|
@@ -311,11 +334,61 @@ async function transcriptBlocks(hit) {
|
|
|
311
334
|
}
|
|
312
335
|
}
|
|
313
336
|
|
|
314
|
-
/** Transcript blocks as the plain lines a text reader (the phone's history view) shows.
|
|
315
|
-
|
|
337
|
+
/** Transcript blocks as the plain lines a text reader (the phone's history view) shows.
|
|
338
|
+
* With `joinScreen`, the current screen follows: the in-flight turn is not in the
|
|
339
|
+
* session file yet (π writes it when the turn ends), so the visible screen is the
|
|
340
|
+
* only bridge — history then flows straight into what the viewer renders below. */
|
|
341
|
+
async function transcriptText(hit, { joinScreen = false } = {}) {
|
|
316
342
|
const blocks = await transcriptBlocks(hit);
|
|
317
|
-
|
|
318
|
-
|
|
343
|
+
const parts = [];
|
|
344
|
+
if (blocks) parts.push(blocks.map((b) => (b.role === "user" ? "❯ " : "● ") + b.text).join("\n"));
|
|
345
|
+
if (joinScreen) {
|
|
346
|
+
try {
|
|
347
|
+
// A text view wants words, not terminal paint: drop OSC replies and every CSI
|
|
348
|
+
// (colors included) — the seed path keeps its paint, this one reads clean.
|
|
349
|
+
const screen = (await run(["pane", "read", hit.id, "--source", "visible", "--format", "text", "--raw"]))
|
|
350
|
+
.replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)?/g, "").replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, "").replace(/\s+$/, "");
|
|
351
|
+
if (screen) {
|
|
352
|
+
if (parts.length) parts.push("──── trở lại hiện tại ────");
|
|
353
|
+
parts.push(screen);
|
|
354
|
+
}
|
|
355
|
+
} catch { /* best-effort seam */ }
|
|
356
|
+
}
|
|
357
|
+
return parts.length ? parts.join("\n") : null;
|
|
358
|
+
}
|
|
359
|
+
|
|
360
|
+
// Input from the phone rides a bounded, coalescing FIFO with in-order acks: adjacent
|
|
361
|
+
// keystroke batches for one pane leave as a single send-keys, every input is acked in
|
|
362
|
+
// submission order, and any ambiguous delivery flips the queue to needsResync — the
|
|
363
|
+
// viewer must re-read the pane, and queued input is never replayed at it.
|
|
364
|
+
let inputQueue = null;
|
|
365
|
+
let inputStamp = 0; // advanced once a write has landed: snapshots older than it are stale
|
|
366
|
+
async function applyInput(event) {
|
|
367
|
+
if (event.kind === "text") await run(["pane", "run", event.paneId, event.text]);
|
|
368
|
+
else await run(["pane", "send-keys", event.paneId, ...event.keys]);
|
|
369
|
+
inputStamp++;
|
|
370
|
+
}
|
|
371
|
+
async function queuedInput(paneId, kind, payload) {
|
|
372
|
+
if (!inputQueue) { // a queue-less path (never in this adapter today) still writes in order
|
|
373
|
+
await applyInput({ paneId, kind, ...payload });
|
|
374
|
+
return null;
|
|
375
|
+
}
|
|
376
|
+
try {
|
|
377
|
+
return await inputQueue.enqueue(paneId, kind, payload);
|
|
378
|
+
} catch (err) {
|
|
379
|
+
if (err?.kind === "needs_resync") throw new RpcError(-32000, "Pane input needs a resync; re-read the pane, never replay", "needs_resync");
|
|
380
|
+
throw err;
|
|
381
|
+
}
|
|
382
|
+
}
|
|
383
|
+
// In-flight snapshot sharing: concurrent readers of one pane share a single read, and a
|
|
384
|
+
// read that began before a write is never served to a caller after it (the `fresh` rule).
|
|
385
|
+
const stitchedInFlight = new Map(); // pane_id → { after, promise }
|
|
386
|
+
async function stitchedRead(hit) {
|
|
387
|
+
const current = stitchedInFlight.get(hit.id);
|
|
388
|
+
if (current && current.after === inputStamp) return current.promise;
|
|
389
|
+
const promise = transcriptText(hit, { joinScreen: true });
|
|
390
|
+
stitchedInFlight.set(hit.id, { after: inputStamp, promise });
|
|
391
|
+
try { return await promise; } finally { if (stitchedInFlight.get(hit.id)?.promise === promise) stitchedInFlight.delete(hit.id); }
|
|
319
392
|
}
|
|
320
393
|
|
|
321
394
|
/** The terminal addresses a doc tree shows. */
|
|
@@ -425,7 +498,7 @@ async function findPane(terminal) {
|
|
|
425
498
|
async function call(method, p, framed, attach, startEvents) {
|
|
426
499
|
switch (method) {
|
|
427
500
|
case "hello":
|
|
428
|
-
return { core, version, generation: 1, framed, features: framed ? ["framed", "attach", "status", ...(interactive ? ["resize_notifications"] : [])] : ["status"], methods: [...methods, ...(framed ? ["terminal.attach"] : []), ...(interactive ? inputMethods : [])], keeps_running_after_logout: true };
|
|
501
|
+
return { core, version, generation: 1, framed, features: framed ? ["framed", "attach", "status", "checksum_reads", ...(interactive ? ["resize_notifications", "input_ack"] : [])] : ["status", "checksum_reads"], methods: [...methods, ...(framed ? ["terminal.attach"] : []), ...(interactive ? inputMethods : [])], keeps_running_after_logout: true };
|
|
429
502
|
case "server.status": return status();
|
|
430
503
|
case "terminal.list": {
|
|
431
504
|
const filters = p.labels ?? {};
|
|
@@ -450,14 +523,18 @@ async function call(method, p, framed, attach, startEvents) {
|
|
|
450
523
|
const { turn } = terminal;
|
|
451
524
|
if (method === "terminal.send") {
|
|
452
525
|
if (!inputText(p.text) || p.wait === true || p.if != null) throw invalid();
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
526
|
+
const ack = await queuedInput(id, "text", { text: p.text });
|
|
527
|
+
return { turn, status: null, started: null, wait: null, ...(ack === null ? {} : { ack }) };
|
|
528
|
+
}
|
|
529
|
+
if (method === "terminal.interrupt") {
|
|
530
|
+
// An interrupt must never sit behind typing already in the queue.
|
|
531
|
+
await run(["pane", "send-keys", id, "ctrl+c"]);
|
|
532
|
+
return { key: "ctrl+c", outcome: "unknown" };
|
|
456
533
|
}
|
|
457
|
-
const keys =
|
|
534
|
+
const keys = p.keys;
|
|
458
535
|
if (!Array.isArray(keys) || !keys.length || keys.length > 32 || keys.some((key) => typeof key !== "string" || !/^(?:(?:ctrl|alt|shift|super)\+)*[a-z0-9][a-z0-9_-]{0,15}$/i.test(key) || key.length > 32)) throw invalid();
|
|
459
|
-
await
|
|
460
|
-
return
|
|
536
|
+
const ack = await queuedInput(id, "keys", { keys });
|
|
537
|
+
return { turn, status: null, ...(ack === null ? {} : { ack }) };
|
|
461
538
|
}
|
|
462
539
|
case "terminal.run": {
|
|
463
540
|
if (!interactive) throw new RpcError(-32601, "This pairing is read-only", "forbidden");
|
|
@@ -504,14 +581,21 @@ async function call(method, p, framed, attach, startEvents) {
|
|
|
504
581
|
}
|
|
505
582
|
const lines = p.lines ?? 0;
|
|
506
583
|
if (!Number.isSafeInteger(lines) || lines < 0) throw invalid();
|
|
584
|
+
// A checksum-stamped read: the viewer that already holds this text sends its stamp
|
|
585
|
+
// back and gets `unchanged` with no body when nothing moved (readChangedCommand
|
|
586
|
+
// semantics — POSIX cksum, no stat). Viewers without a stamp get the full body.
|
|
587
|
+
const prior = typeof p.checksum === "string" && /^[0-9]{1,10} [0-9]{1,20}$/.test(p.checksum) ? p.checksum : null;
|
|
507
588
|
// An agent pane keeps its chat inside itself: serve the transcript as "stitched"
|
|
508
|
-
// history (the core's term for a full-screen app read by scrolling it)
|
|
509
|
-
|
|
589
|
+
// history (the core's term for a full-screen app read by scrolling it), joined to
|
|
590
|
+
// the live screen so the seam never shows a gap mid-turn.
|
|
591
|
+
const transcript = await stitchedRead(hit);
|
|
510
592
|
if (transcript) {
|
|
511
593
|
const all = transcript.split("\n");
|
|
512
594
|
const take = lines > 0 ? all.slice(-Math.min(2000, lines)) : all.slice(-24);
|
|
513
|
-
const text = take.join("\n");
|
|
514
|
-
|
|
595
|
+
const text = take.join("\n").slice(0, 60 * 1024);
|
|
596
|
+
const stamp = cksum(Buffer.from(text, "utf8"));
|
|
597
|
+
if (prior !== null && prior === stamp) return { unchanged: true, checksum: stamp, complete: transcript.length <= 60 * 1024, how: "stitched", why: null };
|
|
598
|
+
return { text, checksum: stamp, complete: transcript.length <= 60 * 1024, how: "stitched", why: null };
|
|
515
599
|
}
|
|
516
600
|
// A shell pane: `recent` carries the history viewers scroll (the phone reads it);
|
|
517
601
|
// a pane with none — fresh — falls back to the on-screen text so it is not blank.
|
|
@@ -594,6 +678,7 @@ async function serve() {
|
|
|
594
678
|
let framed = false;
|
|
595
679
|
let buffer = Buffer.alloc(0);
|
|
596
680
|
const streams = new Map();
|
|
681
|
+
inputQueue = interactive ? new PaneLiveInputQueue(applyInput) : null;
|
|
597
682
|
let nextChannel = 1;
|
|
598
683
|
let timer;
|
|
599
684
|
let polling = false;
|
|
@@ -640,9 +725,15 @@ async function serve() {
|
|
|
640
725
|
out.push("");
|
|
641
726
|
}
|
|
642
727
|
out.push(dim + "──── trở lại hiện tại ────" + reset);
|
|
728
|
+
// The seam: the in-flight turn lives only on the screen, so end the seed with
|
|
729
|
+
// the screen itself — the viewer's first paint then continues it, not jumps.
|
|
730
|
+
try {
|
|
731
|
+
const screen = (await run(["pane", "read", hit.id, "--source", "visible", "--format", "text", "--raw"])).replace(/\s+$/, "");
|
|
732
|
+
if (screen) out.push(screen);
|
|
733
|
+
} catch { /* best-effort seam */ }
|
|
643
734
|
parts.push(Buffer.from(out.join("\r\n") + "\r\n"));
|
|
644
735
|
}
|
|
645
|
-
if (Number.isSafeInteger(p.history) && p.history > 0) {
|
|
736
|
+
if (!blocks && Number.isSafeInteger(p.history) && p.history > 0) {
|
|
646
737
|
try {
|
|
647
738
|
const back = await run(["pane", "read", hit.id, "--source", "recent", "--lines", String(Math.min(2000, p.history)), "--format", "ansi", "--raw"]);
|
|
648
739
|
const lines = back.split(/\r?\n/);
|
|
@@ -767,10 +858,9 @@ async function serve() {
|
|
|
767
858
|
const prev = s.seen.get(t.address);
|
|
768
859
|
if (prev === undefined) out.push({ method: "event", params: { seq: ++s.seq, type: "created", terminal: t.address, data: t } });
|
|
769
860
|
else if (prev.join("\0") !== now.get(t.address).join("\0")) {
|
|
770
|
-
const [title0, cwd0, space0, tabb0, status0
|
|
771
|
-
const [title1, cwd1, space1, tabb1, status1
|
|
772
|
-
if (status0 !== status1) out.push({ method: "event", params: { seq: ++s.seq, type: "status", terminal: t.address, data: { status:
|
|
773
|
-
if (fg0 !== fg1) out.push({ method: "event", params: { seq: ++s.seq, type: "foreground", terminal: t.address, data: t.foreground } });
|
|
861
|
+
const [title0, cwd0, space0, tabb0, status0] = prev;
|
|
862
|
+
const [title1, cwd1, space1, tabb1, status1] = now.get(t.address);
|
|
863
|
+
if (status0 !== status1) out.push({ method: "event", params: { seq: ++s.seq, type: "status", terminal: t.address, data: { status: t.status, records: {}, reported: t.status !== null } } });
|
|
774
864
|
out.push({ method: "event", params: { seq: ++s.seq, type: "labels", terminal: t.address, data: { record: t } } });
|
|
775
865
|
}
|
|
776
866
|
}
|
|
@@ -866,20 +956,26 @@ async function serve() {
|
|
|
866
956
|
clearTimeout(timer);
|
|
867
957
|
clearTimeout(eventTimer);
|
|
868
958
|
for (const channel of streams.keys()) release(channel);
|
|
959
|
+
inputQueue?.resync("connection closed");
|
|
960
|
+
shells.close();
|
|
869
961
|
}
|
|
870
962
|
}
|
|
871
963
|
|
|
872
964
|
const command = args.join(" ");
|
|
873
965
|
try {
|
|
874
966
|
if (command === "--version" || command === "-V") console.log(`hc ${version} (Herdgate ${mode} TUI adapter)`);
|
|
875
|
-
else if (command === "server status" || command === "server status --json")
|
|
967
|
+
else if (command === "server status" || command === "server status --json") {
|
|
968
|
+
const out = JSON.stringify(await status());
|
|
969
|
+
shells.close();
|
|
970
|
+
console.log(out);
|
|
971
|
+
}
|
|
876
972
|
else if (command === "connect" || command === "connect --json") {
|
|
877
973
|
await serve();
|
|
878
974
|
} else {
|
|
879
975
|
console.error("herdgate: TUI adapter supports only connect, --version, and server status");
|
|
880
976
|
process.exitCode = 111;
|
|
881
977
|
}
|
|
882
|
-
} catch {
|
|
883
|
-
console.error(
|
|
978
|
+
} catch (e) {
|
|
979
|
+
console.error(`herdgate: could not query the local Herdr TUI: ${e?.message ?? e}`);
|
|
884
980
|
process.exitCode = 111;
|
|
885
981
|
}
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
// Native Herdr terminal controller. Never interprets a shell command. --takeover makes the
|
|
2
2
|
// latest viewer own the stream: Herdr allows one controller per terminal, and this way a
|
|
3
3
|
// reconnect or a second viewer (phone, desktop) replaces the old one instead of failing.
|
|
4
|
-
import { spawn } from "node:child_process";
|
|
4
|
+
import { execFile, spawn } from "node:child_process";
|
|
5
|
+
import { randomBytes } from "node:crypto";
|
|
5
6
|
|
|
6
7
|
const maxLine = 1024 * 1024;
|
|
7
8
|
|
|
@@ -61,3 +62,259 @@ async function* readFrames(stdout) {
|
|
|
61
62
|
export function validDimension(value) {
|
|
62
63
|
return Number.isInteger(value) && value > 0 && value <= 65535;
|
|
63
64
|
}
|
|
65
|
+
|
|
66
|
+
// POSIX cksum (CRC-32 0x04C11DB7 + byte length, the same `cksum` coreutils prints):
|
|
67
|
+
// a content stamp that needs no stat and survives any transport. `readChangedCommand`
|
|
68
|
+
// stamps file reads with exactly this, so the phone can ask "same as before?" in one line.
|
|
69
|
+
const cksumTable = new Uint32Array(256).map((_, n) => {
|
|
70
|
+
let c = n << 24;
|
|
71
|
+
for (let k = 0; k < 8; k++) c = ((c << 1) ^ ((c & 0x80000000) !== 0 ? 0x04c11db7 : 0)) >>> 0;
|
|
72
|
+
return c >>> 0;
|
|
73
|
+
});
|
|
74
|
+
export function cksum(bytes) {
|
|
75
|
+
let crc = 0;
|
|
76
|
+
for (let i = 0; i < bytes.length; i++) crc = ((crc << 8) ^ cksumTable[((crc >>> 24) ^ bytes[i]) & 0xff]) >>> 0;
|
|
77
|
+
let len = bytes.length;
|
|
78
|
+
while (len > 0) { // the length rides the same CRC, low byte first, no leading zeros
|
|
79
|
+
crc = ((crc << 8) ^ cksumTable[((crc >>> 24) ^ (len & 0xff)) & 0xff]) >>> 0;
|
|
80
|
+
len = Math.floor(len / 256);
|
|
81
|
+
}
|
|
82
|
+
return `${(crc ^ 0xffffffff) >>> 0} ${bytes.length}`;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
const newMarker = () => "HC_" + randomBytes(16).toString("hex");
|
|
86
|
+
|
|
87
|
+
/** One persistent `/bin/sh` with marker framing: every request is `<command> </dev/null`
|
|
88
|
+
* followed by a printf that emits `\n<unique marker> <exit code>\n`. stdin is detached
|
|
89
|
+
* per command so a hungry command cannot swallow the next request; a reply is decoded
|
|
90
|
+
* only once its whole delimiter is present, so chunked output never corrupts multibyte
|
|
91
|
+
* text. The shell is probed with `true` before it counts as alive; any channel failure
|
|
92
|
+
* (write error, early exit, timeout, over-limit) kills the whole generation — the
|
|
93
|
+
* written request is never retried, later requests fall back to one exec per command,
|
|
94
|
+
* and only an explicit reinit() may open the next generation. */
|
|
95
|
+
export function openShellManager({
|
|
96
|
+
exec,
|
|
97
|
+
shell = process.env.HERDR_SHELL || "/bin/sh",
|
|
98
|
+
probeCommand = "true",
|
|
99
|
+
timeoutMs = 4_000,
|
|
100
|
+
limitBytes = 8 * 1024 * 1024,
|
|
101
|
+
} = {}) {
|
|
102
|
+
const fallbackRun = exec || ((command) => new Promise((resolve) => {
|
|
103
|
+
execFile(shell, ["-c", command], { timeout: timeoutMs, maxBuffer: 512 * 1024, windowsHide: true }, (err, stdout) => {
|
|
104
|
+
resolve({ stdout: Buffer.from(stdout ?? ""), code: err && typeof err.code === "number" ? err.code : err ? 1 : 0 });
|
|
105
|
+
});
|
|
106
|
+
}));
|
|
107
|
+
let generation = 1;
|
|
108
|
+
let state = "idle"; // idle | opening | live | dead
|
|
109
|
+
let fails = 0;
|
|
110
|
+
let child = null;
|
|
111
|
+
let buffer = Buffer.alloc(0);
|
|
112
|
+
let waiting = []; // framed requests in submission order; head is decoded first
|
|
113
|
+
const stats = { shells: 0, shellRequests: 0, fallbackRequests: 0 };
|
|
114
|
+
|
|
115
|
+
const failChannel = (reason) => {
|
|
116
|
+
if (state === "dead") return;
|
|
117
|
+
const written = [];
|
|
118
|
+
const unwritten = [];
|
|
119
|
+
for (const req of waiting) (req.written ? written : unwritten).push(req);
|
|
120
|
+
waiting = [];
|
|
121
|
+
state = "dead";
|
|
122
|
+
fails++;
|
|
123
|
+
buffer = Buffer.alloc(0);
|
|
124
|
+
if (child) { try { child.stdin.end(); } catch { /* already gone */ } child.kill(); child = null; }
|
|
125
|
+
for (const req of written) {
|
|
126
|
+
clearTimeout(req.timer);
|
|
127
|
+
req.reject(Object.assign(new Error(`persistent shell failed: ${reason}`), { kind: "shell_failed", noRetry: true }));
|
|
128
|
+
}
|
|
129
|
+
// These were never written, so running them through the fallback is not a retry.
|
|
130
|
+
for (const req of unwritten) fallbackRun(req.command).then(req.resolve, req.reject);
|
|
131
|
+
};
|
|
132
|
+
|
|
133
|
+
const open = () => {
|
|
134
|
+
stats.shells++;
|
|
135
|
+
state = "opening";
|
|
136
|
+
const kid = spawn(shell, [], { stdio: ["pipe", "pipe", "ignore"], windowsHide: true });
|
|
137
|
+
child = kid;
|
|
138
|
+
kid.stdout.on("data", (chunk) => {
|
|
139
|
+
buffer = Buffer.concat([buffer, chunk]);
|
|
140
|
+
if (buffer.length > limitBytes) return failChannel("frame over limit");
|
|
141
|
+
for (;;) {
|
|
142
|
+
const head = waiting[0];
|
|
143
|
+
if (!head || !head.written) break;
|
|
144
|
+
const start = buffer.indexOf(head.delimiter);
|
|
145
|
+
if (start < 0) break;
|
|
146
|
+
const end = buffer.indexOf(10, start + head.delimiter.length);
|
|
147
|
+
if (end < 0) break;
|
|
148
|
+
const code = Number.parseInt(buffer.subarray(start + head.delimiter.length, end).toString("ascii"), 10);
|
|
149
|
+
if (!Number.isInteger(code) || code < 0) return failChannel("corrupt frame");
|
|
150
|
+
const stdout = buffer.subarray(0, start);
|
|
151
|
+
buffer = buffer.subarray(end + 1);
|
|
152
|
+
waiting.shift();
|
|
153
|
+
clearTimeout(head.timer);
|
|
154
|
+
if (head.probe) {
|
|
155
|
+
if (code !== 0) return failChannel("probe failed");
|
|
156
|
+
state = "live";
|
|
157
|
+
}
|
|
158
|
+
head.resolve({ stdout, code });
|
|
159
|
+
pump();
|
|
160
|
+
}
|
|
161
|
+
});
|
|
162
|
+
kid.stdin.on("error", () => { if (child === kid) failChannel("stdin write failed"); });
|
|
163
|
+
kid.on("error", () => { if (child === kid) failChannel("shell did not start"); });
|
|
164
|
+
kid.on("exit", () => { if (child === kid && state !== "dead") failChannel("shell exited"); });
|
|
165
|
+
const probe = { probe: true, command: probeCommand, marker: newMarker(), written: false };
|
|
166
|
+
probe.delimiter = Buffer.from(`\n${probe.marker} `);
|
|
167
|
+
probe.promise = new Promise((resolve, reject) => { probe.resolve = resolve; probe.reject = reject; });
|
|
168
|
+
waiting.push(probe);
|
|
169
|
+
probe.promise.catch(() => {}); // the probe's own failure is reported by failChannel
|
|
170
|
+
};
|
|
171
|
+
|
|
172
|
+
function pump() {
|
|
173
|
+
if (state === "dead" || !child) return;
|
|
174
|
+
const head = waiting[0];
|
|
175
|
+
if (!head || head.written) return;
|
|
176
|
+
if (!head.probe && state !== "live") return; // nothing runs before the probe answers
|
|
177
|
+
head.written = true;
|
|
178
|
+
stats.shellRequests++;
|
|
179
|
+
head.timer = setTimeout(() => failChannel("request timed out"), timeoutMs);
|
|
180
|
+
head.timer.unref?.();
|
|
181
|
+
// The redirect wraps the whole command (braces), so pipelines keep their stdin while
|
|
182
|
+
// no command can ever read the marker stream meant for the next request.
|
|
183
|
+
const frame = `{ ${head.command} ; } </dev/null\nprintf '\\n%s %s\\n' '${head.marker}' "$?"\n`;
|
|
184
|
+
child.stdin.write(frame, (err) => { if (err) failChannel("stdin write failed"); });
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
return {
|
|
188
|
+
execute(command) {
|
|
189
|
+
if (state === "dead") { stats.fallbackRequests++; return fallbackRun(command); }
|
|
190
|
+
if (state === "idle") open();
|
|
191
|
+
const req = { command, marker: newMarker(), written: false };
|
|
192
|
+
req.delimiter = Buffer.from(`\n${req.marker} `);
|
|
193
|
+
const promise = new Promise((resolve, reject) => { req.resolve = resolve; req.reject = reject; });
|
|
194
|
+
req.promise = promise;
|
|
195
|
+
waiting.push(req);
|
|
196
|
+
pump();
|
|
197
|
+
return promise;
|
|
198
|
+
},
|
|
199
|
+
// The only way a failed generation comes back: an explicit new one.
|
|
200
|
+
reinit() {
|
|
201
|
+
failChannel("reinit");
|
|
202
|
+
generation++;
|
|
203
|
+
fails = 0;
|
|
204
|
+
state = "idle";
|
|
205
|
+
},
|
|
206
|
+
// End of the line for this manager: close the shell without failing anyone.
|
|
207
|
+
close() {
|
|
208
|
+
if (!child) { state = "dead"; return; }
|
|
209
|
+
const kid = child;
|
|
210
|
+
child = null;
|
|
211
|
+
state = "dead";
|
|
212
|
+
try { kid.stdin.end(); } catch { /* already gone */ }
|
|
213
|
+
kid.kill();
|
|
214
|
+
},
|
|
215
|
+
get generation() { return generation; },
|
|
216
|
+
get state() { return state; },
|
|
217
|
+
get fails() { return fails; },
|
|
218
|
+
stats,
|
|
219
|
+
};
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
const resyncError = (reason = "pane input needs resync; re-read, never replay") =>
|
|
223
|
+
Object.assign(new Error(reason), { kind: "needs_resync" });
|
|
224
|
+
|
|
225
|
+
/** Keystrokes from the phone ride a bounded FIFO (PaneLiveInputQueue semantics): adjacent
|
|
226
|
+
* keystroke batches for the same pane coalesce Nagle-style, every input is acknowledged
|
|
227
|
+
* in submission order before the next batch is written, and any ambiguous failure —
|
|
228
|
+
* delivery unknown, or the queue overflows — flips the whole queue to needsResync and
|
|
229
|
+
* drops it: the client must resync from a fresh read, and old input is never replayed. */
|
|
230
|
+
export class PaneLiveInputQueue {
|
|
231
|
+
constructor(apply, { limit = 256 } = {}) {
|
|
232
|
+
if (typeof apply !== "function") throw new Error("PaneLiveInputQueue needs an apply function");
|
|
233
|
+
this.apply = apply;
|
|
234
|
+
this.limit = limit;
|
|
235
|
+
this.state = "live"; // live | needsResync
|
|
236
|
+
this.enqueuedCount = 0;
|
|
237
|
+
this.acknowledgedCount = 0;
|
|
238
|
+
this.droppedCount = 0;
|
|
239
|
+
this.pending = [];
|
|
240
|
+
this.pumping = false;
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
enqueue(paneId, kind, payload = {}) {
|
|
244
|
+
if (this.state !== "live") return Promise.reject(resyncError());
|
|
245
|
+
if (this.pending.length >= this.limit) {
|
|
246
|
+
this.resync("input queue overflow");
|
|
247
|
+
return Promise.reject(resyncError("input queue overflow"));
|
|
248
|
+
}
|
|
249
|
+
const tail = this.pending[this.pending.length - 1];
|
|
250
|
+
if (kind === "keys" && tail && !tail.sent && tail.paneId === paneId && tail.kind === "keys" && Array.isArray(payload.keys)) {
|
|
251
|
+
tail.keys = tail.keys.concat(payload.keys); // one send-keys for a burst of keystrokes
|
|
252
|
+
return this.claim(tail);
|
|
253
|
+
}
|
|
254
|
+
const event = { paneId, kind, text: payload.text, keys: payload.keys ? [...payload.keys] : undefined, sent: false, waiters: [] };
|
|
255
|
+
this.pending.push(event);
|
|
256
|
+
const promise = this.claim(event);
|
|
257
|
+
queueMicrotask(() => this.pump()); // a beat to gather a burst before the write starts
|
|
258
|
+
return promise;
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
/** Drop not-yet-sent input for a pane (the viewer switched away from it). */
|
|
262
|
+
abandon(paneId) {
|
|
263
|
+
if (this.state !== "live") return;
|
|
264
|
+
this.pending = this.pending.filter((event) => {
|
|
265
|
+
if (event.paneId !== paneId || event.sent) return true;
|
|
266
|
+
this.droppedCount += event.waiters.length;
|
|
267
|
+
for (const waiter of event.waiters) waiter.reject(Object.assign(new Error("pane input abandoned"), { kind: "abandoned" }));
|
|
268
|
+
return false;
|
|
269
|
+
});
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
resync(reason = "pane input needs resync") {
|
|
273
|
+
if (this.state !== "live") return;
|
|
274
|
+
this.state = "needsResync";
|
|
275
|
+
const events = this.pending;
|
|
276
|
+
this.pending = [];
|
|
277
|
+
for (const event of events) {
|
|
278
|
+
this.droppedCount += event.waiters.length;
|
|
279
|
+
for (const waiter of event.waiters) waiter.reject(resyncError(reason));
|
|
280
|
+
}
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
claim(event) {
|
|
284
|
+
const seq = ++this.enqueuedCount;
|
|
285
|
+
return new Promise((resolve, reject) => event.waiters.push({ seq, resolve, reject }));
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
async pump() {
|
|
289
|
+
if (this.pumping || this.state !== "live") return;
|
|
290
|
+
this.pumping = true;
|
|
291
|
+
try {
|
|
292
|
+
while (this.pending.length && this.state === "live") {
|
|
293
|
+
const event = this.pending[0];
|
|
294
|
+
event.sent = true;
|
|
295
|
+
let failure = null;
|
|
296
|
+
try {
|
|
297
|
+
await this.apply({ paneId: event.paneId, kind: event.kind, text: event.text, keys: event.keys });
|
|
298
|
+
} catch (err) {
|
|
299
|
+
// The host answered no: a refusal is a refusal — this input is done, the rest drain on.
|
|
300
|
+
// Anything ambiguous (delivery unknown) leaves the channel untrustworthy: resync.
|
|
301
|
+
if (err && err.definitive === true) failure = err;
|
|
302
|
+
else return this.resync(err?.message ?? "pane input delivery failed");
|
|
303
|
+
}
|
|
304
|
+
this.pending.shift();
|
|
305
|
+
this.acknowledge(event, failure);
|
|
306
|
+
}
|
|
307
|
+
} finally {
|
|
308
|
+
this.pumping = false;
|
|
309
|
+
}
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
/** Acks come back strictly in submission order, one count per accepted input. */
|
|
313
|
+
acknowledge(event, failure) {
|
|
314
|
+
for (const waiter of event.waiters) {
|
|
315
|
+
this.acknowledgedCount++;
|
|
316
|
+
if (failure) waiter.reject(failure);
|
|
317
|
+
else waiter.resolve(this.acknowledgedCount);
|
|
318
|
+
}
|
|
319
|
+
}
|
|
320
|
+
}
|