@howaboua/pi-shepherdr 0.2.26 → 0.2.28-core.11.1.gc09f7abbc5a5

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 (97) hide show
  1. package/CHANGELOG.md +5 -0
  2. package/README.md +40 -44
  3. package/index.ts +7 -1
  4. package/package.json +5 -5
  5. package/src/agent-identity.ts +3 -3
  6. package/src/agents-contract.ts +1 -5
  7. package/src/agents-discovery.ts +20 -46
  8. package/src/agents-focus.ts +21 -20
  9. package/src/agents-spawn.ts +4 -17
  10. package/src/agents-tool.ts +7 -20
  11. package/src/agents-work.ts +4 -3
  12. package/src/attachment-protocol.ts +1 -0
  13. package/src/attachment.ts +6 -2
  14. package/src/board/host.ts +1 -1
  15. package/src/close-idle.ts +2 -9
  16. package/src/control-panel/index.ts +2 -4
  17. package/src/control-panel/items.ts +1 -11
  18. package/src/control-panel/view.ts +3 -9
  19. package/src/controller.ts +1 -4
  20. package/src/core/AGENTS.md +8 -4
  21. package/src/core/admission-broker.mjs +235 -0
  22. package/src/core/admission-endpoint.ts +180 -0
  23. package/src/core/admission-owner.mjs +52 -0
  24. package/src/core/admission-startup.ts +130 -0
  25. package/src/core/admission.ts +181 -0
  26. package/src/core/agents.ts +102 -0
  27. package/src/core/backend.ts +116 -84
  28. package/src/core/client.ts +16 -0
  29. package/src/core/focus-channel-helper.mjs +6 -27
  30. package/src/core/focus-channel-wire.mjs +9 -6
  31. package/src/core/focus-channel.ts +5 -3
  32. package/src/core/focus-window.ts +15 -4
  33. package/src/core/helper-bootstrap.mjs +70 -0
  34. package/src/core/helper-context.mjs +98 -0
  35. package/src/core/helper-core.mjs +121 -0
  36. package/src/core/machines.ts +30 -0
  37. package/src/core/registration.ts +7 -2
  38. package/src/core/remote-endpoint.ts +80 -76
  39. package/src/core/remote-helper.ts +322 -0
  40. package/src/core/remote-reader.ts +3 -42
  41. package/src/core/remote-service.mjs +241 -0
  42. package/src/core/remote-transport.ts +290 -0
  43. package/src/core/spawn.ts +21 -21
  44. package/src/core/terminal-peer.mjs +57 -0
  45. package/src/core/terminal.ts +4 -2
  46. package/src/fleet/catalog.ts +16 -58
  47. package/src/fleet/connection.ts +9 -18
  48. package/src/fleet/index.ts +38 -76
  49. package/src/fleet/inspection.ts +9 -22
  50. package/src/fleet/machine.ts +28 -12
  51. package/src/fleet/monitor.ts +8 -29
  52. package/src/fleet/persistence.ts +2 -2
  53. package/src/fleet/reconnect.ts +5 -3
  54. package/src/fleet/setup.ts +6 -16
  55. package/src/launch-contract.ts +0 -3
  56. package/src/launch-location.ts +4 -132
  57. package/src/launch.ts +18 -144
  58. package/src/messages/attribution.ts +5 -13
  59. package/src/messages/events.ts +5 -9
  60. package/src/messages/focus.ts +2 -7
  61. package/src/monitor-events.ts +14 -43
  62. package/src/monitor-extension-messages.ts +5 -6
  63. package/src/monitor-record.ts +4 -0
  64. package/src/monitor-state.ts +1 -101
  65. package/src/monitor.ts +38 -66
  66. package/src/peer-inbox.ts +21 -27
  67. package/src/remote/context-relay.ts +25 -10
  68. package/src/remote/shepherdr-channel.mjs +1 -1
  69. package/src/remote/shepherdr-checkpoints.mjs +51 -102
  70. package/src/remote/shepherdr-context.mjs +1 -1
  71. package/src/remote/shepherdr-peer.mjs +19 -24
  72. package/src/saved-context.ts +62 -0
  73. package/src/settlement/collector.ts +29 -9
  74. package/src/settlement/index.ts +25 -6
  75. package/src/shared-context-host.ts +19 -3
  76. package/src/shared-context.ts +9 -3
  77. package/src/spawn-context.ts +9 -1
  78. package/src/spawn-ownership.ts +1 -1
  79. package/src/ssh-setup.ts +40 -73
  80. package/src/types.ts +4 -8
  81. package/src/widget.ts +7 -2
  82. package/src/worker-ownership.ts +2 -8
  83. package/src/worker-service.ts +3 -13
  84. package/src/core/context-relay.mjs +0 -111
  85. package/src/core/remote-exec.ts +0 -122
  86. package/src/core/remote-helper.mjs +0 -244
  87. package/src/core/remote-relay.ts +0 -191
  88. package/src/core/request.ts +0 -124
  89. package/src/herdr-client.ts +0 -364
  90. package/src/herdr.ts +0 -268
  91. package/src/machine-catalog.ts +0 -83
  92. package/src/monitor-event.ts +0 -84
  93. package/src/remote/client.ts +0 -127
  94. package/src/remote/deployment.ts +0 -179
  95. package/src/remote/focus-channels.ts +0 -89
  96. package/src/remote/shepherdr.mjs +0 -504
  97. package/src/remote/transport.ts +0 -369
@@ -0,0 +1,52 @@
1
+ import { createHash } from "node:crypto";
2
+ import { lstat, rmdir, unlink } from "node:fs/promises";
3
+
4
+ /** @typedef {{path:string,marker:string}} StartupLease */
5
+
6
+ /** Startup travels through stdin, not argv: endpoint names stay private to the OS user.
7
+ * The parent atomically transfers its directory marker before allowing the child to bind.
8
+ * @returns {Promise<{endpoint:string, lease:StartupLease}>}
9
+ */
10
+ export async function readAdmissionStart() {
11
+ const timer = setTimeout(
12
+ () => process.stdin.destroy(new Error("Startup expired")),
13
+ 5000,
14
+ );
15
+ try {
16
+ let frame = "";
17
+ for await (const chunk of process.stdin) {
18
+ frame += chunk;
19
+ if (Buffer.byteLength(frame) > 8192)
20
+ throw new Error("Invalid startup frame");
21
+ }
22
+ const value = JSON.parse(frame);
23
+ if (
24
+ !value ||
25
+ typeof value.endpoint !== "string" ||
26
+ !value.endpoint ||
27
+ !value.lease ||
28
+ typeof value.lease.path !== "string" ||
29
+ typeof value.lease.marker !== "string" ||
30
+ !new RegExp(`^${process.pid}-[a-zA-Z0-9]+$`).test(value.lease.marker) ||
31
+ createHash("sha256").update(value.endpoint).digest("hex") !==
32
+ process.argv[2]
33
+ )
34
+ throw new Error("Invalid startup owner");
35
+ const marker = await lstat(`${value.lease.path}/${value.lease.marker}`);
36
+ if (!marker.isFile() || (process.getuid && marker.uid !== process.getuid()))
37
+ throw new Error("Startup ownership changed");
38
+ return value;
39
+ } finally {
40
+ clearTimeout(timer);
41
+ }
42
+ }
43
+
44
+ /** @param {StartupLease} lease */
45
+ export async function releaseAdmissionStart(lease) {
46
+ await unlink(`${lease.path}/${lease.marker}`).catch((error) => {
47
+ if (error.code !== "ENOENT") throw error;
48
+ });
49
+ await rmdir(lease.path).catch((error) => {
50
+ if (!["ENOENT", "ENOTEMPTY"].includes(error.code)) throw error;
51
+ });
52
+ }
@@ -0,0 +1,130 @@
1
+ import {
2
+ lstat,
3
+ mkdtemp,
4
+ readdir,
5
+ rename,
6
+ rmdir,
7
+ unlink,
8
+ writeFile,
9
+ } from "node:fs/promises";
10
+
11
+ const missing = (error: unknown) =>
12
+ error instanceof Error && "code" in error && error.code === "ENOENT";
13
+
14
+ interface StartupLock {
15
+ handoff(pid: number): Promise<{ path: string; marker: string }>;
16
+ release(): Promise<void>;
17
+ }
18
+
19
+ export function pause(signal: AbortSignal): Promise<void> {
20
+ return new Promise((resolve, reject) => {
21
+ const abort = () => {
22
+ clearTimeout(timer);
23
+ reject(signal.reason);
24
+ };
25
+ const timer = setTimeout(() => {
26
+ signal.removeEventListener("abort", abort);
27
+ resolve();
28
+ }, 25);
29
+ signal.addEventListener("abort", abort, { once: true });
30
+ if (signal.aborted) abort();
31
+ });
32
+ }
33
+
34
+ /** Filesystem sockets need stale recovery; a populated directory is atomic election.
35
+ * Never rename a stale lock: another client might already have replaced it.
36
+ */
37
+ export async function lockStartup(
38
+ path: string,
39
+ signal: AbortSignal,
40
+ ): Promise<StartupLock> {
41
+ const lock = `${path}.starting`;
42
+ const candidate = await mkdtemp(`${lock}-${process.pid}-`);
43
+ const owner = `${process.pid}-${candidate.slice(candidate.lastIndexOf("-") + 1)}`;
44
+ await writeFile(`${candidate}/${owner}`, "", { mode: 0o600 });
45
+ try {
46
+ for (;;) {
47
+ signal.throwIfAborted();
48
+ try {
49
+ await rename(candidate, lock);
50
+ break;
51
+ } catch (error) {
52
+ if (
53
+ !(
54
+ error instanceof Error &&
55
+ "code" in error &&
56
+ ["ENOTEMPTY", "EEXIST"].includes(String(error.code))
57
+ )
58
+ )
59
+ throw error;
60
+ }
61
+ try {
62
+ const entries = await readdir(lock);
63
+ const previous = entries.length === 1 ? entries[0] : undefined;
64
+ if (previous && /^[1-9][0-9]*-[a-zA-Z0-9]+$/.test(previous)) {
65
+ let dead = false;
66
+ try {
67
+ process.kill(Number(previous.split("-")[0]), 0);
68
+ } catch (error) {
69
+ if (
70
+ error instanceof Error &&
71
+ "code" in error &&
72
+ error.code === "ESRCH"
73
+ )
74
+ dead = true;
75
+ }
76
+ if (dead) await unlink(`${lock}/${previous}`);
77
+ }
78
+ // A published lock is never empty. Recover a crash during removal,
79
+ // without removing a concurrently published populated replacement.
80
+ if (!entries.length && Date.now() - (await lstat(lock)).mtimeMs > 1000)
81
+ await rmdir(lock);
82
+ if (previous) {
83
+ try {
84
+ await rmdir(lock);
85
+ } catch (error) {
86
+ if (
87
+ !(
88
+ error instanceof Error &&
89
+ "code" in error &&
90
+ ["ENOTEMPTY", "ENOENT"].includes(String(error.code))
91
+ )
92
+ )
93
+ throw error;
94
+ }
95
+ }
96
+ } catch (error) {
97
+ if (!missing(error)) throw error;
98
+ }
99
+ await pause(signal);
100
+ }
101
+ } catch (error) {
102
+ await unlink(`${candidate}/${owner}`);
103
+ await rmdir(candidate);
104
+ throw error;
105
+ }
106
+ return {
107
+ async handoff(pid) {
108
+ const marker = `${pid}-${owner.slice(owner.indexOf("-") + 1)}`;
109
+ // The directory stays populated throughout transfer. A child must
110
+ // verify this marker before binding, even if its parent has exited.
111
+ await rename(`${lock}/${owner}`, `${lock}/${marker}`);
112
+ return { path: lock, marker };
113
+ },
114
+ async release() {
115
+ await unlink(`${lock}/${owner}`).catch((error: unknown) => {
116
+ if (!missing(error)) throw error;
117
+ });
118
+ await rmdir(lock).catch((error: unknown) => {
119
+ if (
120
+ !(
121
+ error instanceof Error &&
122
+ "code" in error &&
123
+ ["ENOTEMPTY", "ENOENT"].includes(String(error.code))
124
+ )
125
+ )
126
+ throw error;
127
+ });
128
+ },
129
+ };
130
+ }
@@ -0,0 +1,181 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import type { Socket } from "node:net";
3
+ import { admissionEndpoint, connectAdmission } from "./admission-endpoint.js";
4
+
5
+ type Lane = "launch" | "bulk";
6
+ interface Waiting {
7
+ resolve(): void;
8
+ reject(error: Error): void;
9
+ }
10
+
11
+ /** Owns one client's queue and connection, not execution or agent identity. */
12
+ export class CoreAdmission {
13
+ private readonly lifetime = new AbortController();
14
+ private readonly waiting = new Map<string, Waiting>();
15
+ private connection: Promise<Socket> | undefined;
16
+ private socket: Socket | undefined;
17
+ private ended: Error | undefined;
18
+ private buffer = "";
19
+ private readonly core: string;
20
+ private readonly destination: string;
21
+ constructor(core: string, destination = "local") {
22
+ this.core = core;
23
+ this.destination = destination;
24
+ }
25
+
26
+ close(): void {
27
+ this.fail(new Error("Agent connection closed"));
28
+ }
29
+
30
+ private fail(error: Error): void {
31
+ if (this.ended) return;
32
+ this.ended = error;
33
+ this.lifetime.abort(error);
34
+ this.socket?.destroy();
35
+ for (const waiter of this.waiting.values()) waiter.reject(error);
36
+ this.waiting.clear();
37
+ }
38
+
39
+ private disconnected(socket: Socket): void {
40
+ if (this.socket !== socket) return;
41
+ this.socket = undefined;
42
+ this.connection = undefined;
43
+ this.buffer = "";
44
+ socket.destroy();
45
+ // Only callers not yet admitted fail. Accepted work keeps its original
46
+ // execution/cleanup owner and is never replayed after broker loss.
47
+ for (const waiter of this.waiting.values())
48
+ waiter.reject(
49
+ new Error("Agent connection lost before the operation started"),
50
+ );
51
+ }
52
+
53
+ private async open(): Promise<Socket> {
54
+ const path = await admissionEndpoint(this.core, this.destination);
55
+ const startup = AbortSignal.any([
56
+ this.lifetime.signal,
57
+ AbortSignal.timeout(5000),
58
+ ]);
59
+ const socket = await connectAdmission(path, startup);
60
+ if (this.ended) {
61
+ socket.destroy();
62
+ throw this.ended;
63
+ }
64
+ this.socket = socket;
65
+ socket.setEncoding("utf8");
66
+ socket.on("error", () => this.disconnected(socket));
67
+ socket.on("close", () => this.disconnected(socket));
68
+ socket.on("data", (chunk: string) => {
69
+ try {
70
+ this.buffer += chunk;
71
+ for (;;) {
72
+ const end = this.buffer.indexOf("\n");
73
+ if (
74
+ Buffer.byteLength(
75
+ end < 0 ? this.buffer : this.buffer.slice(0, end),
76
+ ) > 8192
77
+ )
78
+ throw new Error("Invalid agent connection response");
79
+ if (end < 0) break;
80
+ const value: unknown = JSON.parse(this.buffer.slice(0, end));
81
+ this.buffer = this.buffer.slice(end + 1);
82
+ if (
83
+ !value ||
84
+ typeof value !== "object" ||
85
+ !("id" in value) ||
86
+ typeof value.id !== "string" ||
87
+ !("state" in value)
88
+ )
89
+ throw new Error("Invalid agent connection response");
90
+ const waiter = this.waiting.get(value.id);
91
+ if (value.state === "granted") waiter?.resolve();
92
+ else if (
93
+ value.state === "error" &&
94
+ "message" in value &&
95
+ typeof value.message === "string"
96
+ )
97
+ waiter?.reject(
98
+ new Error(
99
+ "Agent operation could not start: concurrent operation limit reached",
100
+ ),
101
+ );
102
+ else throw new Error("Invalid agent connection response");
103
+ }
104
+ } catch (error) {
105
+ this.fail(error instanceof Error ? error : new Error(String(error)));
106
+ }
107
+ });
108
+ return socket;
109
+ }
110
+
111
+ /** Deadline is for admission only. Execution owns its existing cancellation/timeout. */
112
+ async run<T>(
113
+ lane: Lane,
114
+ execute: () => Promise<T>,
115
+ signal?: AbortSignal,
116
+ ): Promise<T> {
117
+ signal?.throwIfAborted();
118
+ if (this.ended) throw this.ended;
119
+ if (this.waiting.size >= 64)
120
+ throw new Error(
121
+ "Agent operation could not start: concurrent operation limit reached",
122
+ );
123
+ const id = randomUUID();
124
+ const admission = AbortSignal.any([
125
+ this.lifetime.signal,
126
+ AbortSignal.timeout(90_000),
127
+ ...(signal ? [signal] : []),
128
+ ]);
129
+ let socket: Socket | undefined;
130
+ let resolve!: () => void;
131
+ let reject!: (error: Error) => void;
132
+ const granted = new Promise<void>((yes, no) => {
133
+ resolve = yes;
134
+ reject = no;
135
+ });
136
+ // Register before connection startup: cancellation cannot submit queued work.
137
+ this.waiting.set(id, { resolve, reject });
138
+ const abort = () =>
139
+ reject(
140
+ new Error(
141
+ admission.reason?.name === "TimeoutError"
142
+ ? "Agent operation could not start before its deadline"
143
+ : "Agent operation cancelled before starting",
144
+ { cause: admission.reason },
145
+ ),
146
+ );
147
+ admission.addEventListener("abort", abort, { once: true });
148
+ if (admission.aborted) abort();
149
+ const connecting = (this.connection ??= this.open());
150
+ void connecting.then(
151
+ (connection) => {
152
+ socket = connection;
153
+ if (!admission.aborted && this.waiting.has(id))
154
+ socket.write(`${JSON.stringify({ op: "acquire", id, lane })}\n`);
155
+ },
156
+ (error: unknown) => {
157
+ if (this.connection !== connecting) return;
158
+ this.connection = undefined;
159
+ for (const waiter of this.waiting.values())
160
+ waiter.reject(
161
+ new Error(
162
+ "Agent operations could not start. Check Core and local runtime permissions",
163
+ { cause: error },
164
+ ),
165
+ );
166
+ },
167
+ );
168
+ try {
169
+ await granted;
170
+ admission.throwIfAborted();
171
+ admission.removeEventListener("abort", abort);
172
+ // Broker failure never retries accepted work. Existing operation owns cleanup.
173
+ return await execute();
174
+ } finally {
175
+ admission.removeEventListener("abort", abort);
176
+ this.waiting.delete(id);
177
+ if (socket && !socket.destroyed)
178
+ socket.write(`${JSON.stringify({ op: "release", id })}\n`);
179
+ }
180
+ }
181
+ }
@@ -0,0 +1,102 @@
1
+ import type { PaneInfo, SessionSnapshot } from "../types.js";
2
+ import type { CoreConnection } from "./backend.js";
3
+ import { object } from "./protocol.js";
4
+ import { terminalPane, terminalSnapshot } from "./terminal.js";
5
+ import { terminalPeer } from "./terminal-peer.mjs";
6
+
7
+ export async function getSnapshot(
8
+ client: CoreConnection,
9
+ ): Promise<SessionSnapshot> {
10
+ return terminalSnapshot(await client.core.localSnapshot());
11
+ }
12
+
13
+ export async function getAgent(
14
+ client: CoreConnection,
15
+ target: string,
16
+ ): Promise<PaneInfo> {
17
+ if (/^t[1-9][0-9bcdfghjkmnpqrstvwxyz]*$/.test(target)) {
18
+ try {
19
+ return terminalPane(
20
+ await client.core.request("terminal.get", { terminal: target }),
21
+ );
22
+ } catch (error) {
23
+ if (
24
+ !(
25
+ error instanceof Error &&
26
+ "kind" in error &&
27
+ error.kind === "not_found"
28
+ )
29
+ )
30
+ throw error;
31
+ }
32
+ }
33
+ const snapshot = await getSnapshot(client);
34
+ const matches = snapshot.agents.filter((agent) => agent.name === target);
35
+ if (matches.length > 1)
36
+ throw new Error("Agent name is ambiguous; use its terminal address");
37
+ const agent = matches[0];
38
+ if (!agent)
39
+ throw Object.assign(
40
+ new Error(
41
+ `No Pi agent matches ${JSON.stringify(target)}; use the exact target returned by spawn/find`,
42
+ ),
43
+ { kind: "not_found" },
44
+ );
45
+ return terminalPane(
46
+ await client.core.request("terminal.get", { terminal: agent.terminal_id }),
47
+ );
48
+ }
49
+
50
+ export async function getCurrentPane(
51
+ client: CoreConnection,
52
+ ): Promise<PaneInfo> {
53
+ const terminal = process.env["HC_TERMINAL_ID"];
54
+ if (!terminal || client.remote)
55
+ throw new Error(
56
+ "Cannot identify this terminal; run Pi inside a local Core terminal",
57
+ );
58
+ return terminalPane(await client.core.request("terminal.get", { terminal }));
59
+ }
60
+
61
+ export async function resolvePiAgent(
62
+ client: CoreConnection,
63
+ target: string,
64
+ controllingPaneId = process.env["HC_TERMINAL_ID"],
65
+ ): Promise<PaneInfo> {
66
+ const agent = await getAgent(client, target);
67
+ if (agent.agent !== "pi") throw new Error(`${target} is not a Pi agent`);
68
+ if (controllingPaneId && agent.terminal_id === controllingPaneId)
69
+ throw new Error("refusing to target the controlling Pi session");
70
+ return agent;
71
+ }
72
+
73
+ export function sessionPath(agent: PaneInfo): string | undefined {
74
+ return agent.agent_session?.kind === "path"
75
+ ? agent.agent_session.value
76
+ : undefined;
77
+ }
78
+
79
+ export async function closeTerminal(
80
+ client: CoreConnection,
81
+ terminal: string,
82
+ ): Promise<void> {
83
+ await terminalPeer((method, params) =>
84
+ client.core.request(method, params),
85
+ ).closeTerminal(terminal);
86
+ }
87
+
88
+ export async function readTerminal(
89
+ client: CoreConnection,
90
+ terminal: string,
91
+ lines: number,
92
+ ): Promise<{ text: string; truncated: boolean }> {
93
+ const result = object(
94
+ await client.core.request("terminal.read", { terminal, lines }),
95
+ );
96
+ if (
97
+ typeof result["text"] !== "string" ||
98
+ typeof result["complete"] !== "boolean"
99
+ )
100
+ throw new Error("Core returned no terminal text");
101
+ return { text: result["text"], truncated: !result["complete"] };
102
+ }