@howaboua/pi-shepherdr 0.2.27 → 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 (96) hide show
  1. package/README.md +40 -44
  2. package/index.ts +7 -1
  3. package/package.json +3 -3
  4. package/src/agent-identity.ts +3 -3
  5. package/src/agents-contract.ts +1 -5
  6. package/src/agents-discovery.ts +20 -46
  7. package/src/agents-focus.ts +21 -20
  8. package/src/agents-spawn.ts +4 -17
  9. package/src/agents-tool.ts +3 -19
  10. package/src/agents-work.ts +4 -3
  11. package/src/attachment-protocol.ts +1 -0
  12. package/src/attachment.ts +6 -2
  13. package/src/board/host.ts +1 -1
  14. package/src/close-idle.ts +2 -9
  15. package/src/control-panel/index.ts +2 -4
  16. package/src/control-panel/items.ts +1 -11
  17. package/src/control-panel/view.ts +3 -9
  18. package/src/controller.ts +1 -4
  19. package/src/core/AGENTS.md +7 -4
  20. package/src/core/admission-broker.mjs +235 -0
  21. package/src/core/admission-endpoint.ts +180 -0
  22. package/src/core/admission-owner.mjs +52 -0
  23. package/src/core/admission-startup.ts +130 -0
  24. package/src/core/admission.ts +181 -0
  25. package/src/core/agents.ts +102 -0
  26. package/src/core/backend.ts +116 -84
  27. package/src/core/client.ts +16 -0
  28. package/src/core/focus-channel-helper.mjs +6 -27
  29. package/src/core/focus-channel-wire.mjs +9 -6
  30. package/src/core/focus-channel.ts +5 -3
  31. package/src/core/focus-window.ts +15 -4
  32. package/src/core/helper-bootstrap.mjs +70 -0
  33. package/src/core/helper-context.mjs +98 -0
  34. package/src/core/helper-core.mjs +121 -0
  35. package/src/core/machines.ts +30 -0
  36. package/src/core/registration.ts +7 -2
  37. package/src/core/remote-endpoint.ts +80 -74
  38. package/src/core/remote-helper.ts +322 -0
  39. package/src/core/remote-reader.ts +3 -42
  40. package/src/core/remote-service.mjs +241 -0
  41. package/src/core/remote-transport.ts +290 -0
  42. package/src/core/spawn.ts +20 -20
  43. package/src/core/terminal-peer.mjs +57 -0
  44. package/src/core/terminal.ts +4 -2
  45. package/src/fleet/catalog.ts +16 -58
  46. package/src/fleet/connection.ts +9 -18
  47. package/src/fleet/index.ts +38 -76
  48. package/src/fleet/inspection.ts +9 -22
  49. package/src/fleet/machine.ts +28 -12
  50. package/src/fleet/monitor.ts +8 -29
  51. package/src/fleet/persistence.ts +2 -2
  52. package/src/fleet/reconnect.ts +5 -3
  53. package/src/fleet/setup.ts +6 -16
  54. package/src/launch-contract.ts +0 -3
  55. package/src/launch-location.ts +4 -132
  56. package/src/launch.ts +18 -144
  57. package/src/messages/attribution.ts +5 -13
  58. package/src/messages/events.ts +5 -9
  59. package/src/messages/focus.ts +2 -7
  60. package/src/monitor-events.ts +14 -43
  61. package/src/monitor-extension-messages.ts +5 -6
  62. package/src/monitor-record.ts +4 -0
  63. package/src/monitor-state.ts +1 -101
  64. package/src/monitor.ts +38 -66
  65. package/src/peer-inbox.ts +21 -27
  66. package/src/remote/context-relay.ts +25 -10
  67. package/src/remote/shepherdr-channel.mjs +1 -1
  68. package/src/remote/shepherdr-checkpoints.mjs +51 -102
  69. package/src/remote/shepherdr-context.mjs +1 -1
  70. package/src/remote/shepherdr-peer.mjs +19 -24
  71. package/src/saved-context.ts +62 -0
  72. package/src/settlement/collector.ts +29 -9
  73. package/src/settlement/index.ts +25 -6
  74. package/src/shared-context-host.ts +19 -3
  75. package/src/shared-context.ts +9 -3
  76. package/src/spawn-context.ts +9 -1
  77. package/src/spawn-ownership.ts +1 -1
  78. package/src/ssh-setup.ts +40 -73
  79. package/src/types.ts +4 -8
  80. package/src/widget.ts +7 -2
  81. package/src/worker-ownership.ts +2 -8
  82. package/src/worker-service.ts +3 -13
  83. package/src/core/context-relay.mjs +0 -111
  84. package/src/core/remote-exec.ts +0 -122
  85. package/src/core/remote-helper.mjs +0 -244
  86. package/src/core/remote-relay.ts +0 -191
  87. package/src/core/request.ts +0 -124
  88. package/src/herdr-client.ts +0 -364
  89. package/src/herdr.ts +0 -268
  90. package/src/machine-catalog.ts +0 -83
  91. package/src/monitor-event.ts +0 -84
  92. package/src/remote/client.ts +0 -127
  93. package/src/remote/deployment.ts +0 -179
  94. package/src/remote/focus-channels.ts +0 -89
  95. package/src/remote/shepherdr.mjs +0 -504
  96. package/src/remote/transport.ts +0 -369
@@ -38,6 +38,7 @@ const ContextLink = Type.Object({
38
38
  alias: AgentPath,
39
39
  controllerAlias: AgentPath,
40
40
  controllerFile: Type.Optional(Type.String()),
41
+ controllerMachine: Type.Optional(Type.String({ minLength: 1 })),
41
42
  controllerNotes: Type.Unknown(),
42
43
  targetNotes: Type.Unknown(),
43
44
  });
package/src/attachment.ts CHANGED
@@ -20,8 +20,8 @@ import {
20
20
  import { AttachmentRouting } from "./attachment-routing.js";
21
21
  import { AttachmentTarget } from "./attachment-target.js";
22
22
  import type { AgentBoard } from "./board/host.js";
23
+ import { sessionPath } from "./core/agents.js";
23
24
  import type { ConnectedMachine } from "./fleet/index.js";
24
- import { sessionPath } from "./herdr.js";
25
25
  import { sessionContextPath } from "./remote/shepherdr-context.mjs";
26
26
  import type { PaneInfo } from "./types.js";
27
27
 
@@ -30,16 +30,19 @@ export class AgentAttachment {
30
30
  private readonly pi: ExtensionAPI;
31
31
  private readonly board: AgentBoard;
32
32
  private readonly notes: AttachmentNotes;
33
+ private readonly localMachine: () => string;
33
34
  readonly target: AttachmentTarget;
34
35
  readonly routing: AttachmentRouting;
35
36
  constructor(
36
37
  pi: ExtensionAPI,
37
38
  board: AgentBoard,
38
39
  getService: () => ContextSharingService | undefined,
40
+ localMachine: () => string,
39
41
  ) {
40
42
  this.pi = pi;
41
43
  this.board = board;
42
44
  this.notes = new AttachmentNotes(getService);
45
+ this.localMachine = localMachine;
43
46
  this.target = new AttachmentTarget(pi, board, getService, this.notes);
44
47
  this.routing = new AttachmentRouting(getService, this.notes);
45
48
  }
@@ -134,7 +137,8 @@ export class AgentAttachment {
134
137
  target: current.context,
135
138
  alias: `/${current.sessionId}`,
136
139
  controllerAlias: `/${controllerSessionId}`,
137
- ...(runtime.local ? { controllerFile } : {}),
140
+ controllerFile,
141
+ controllerMachine: this.localMachine(),
138
142
  controllerNotes: await this.notes.export(ctx),
139
143
  targetNotes: current.notes,
140
144
  },
package/src/board/host.ts CHANGED
@@ -14,8 +14,8 @@ import {
14
14
  type BoardRuntime,
15
15
  discoverBoard,
16
16
  } from "@howaboua/pi-agent-board/runtime";
17
+ import { sessionPath } from "../core/agents.js";
17
18
  import type { AgentFleet, ConnectedMachine } from "../fleet/index.js";
18
- import { sessionPath } from "../herdr.js";
19
19
  import { boardBriefing, boardMigrationWarning } from "../messages/guidance.js";
20
20
  import {
21
21
  requestContext,
package/src/close-idle.ts CHANGED
@@ -1,7 +1,6 @@
1
1
  import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
2
- import { CoreConnection } from "./core/backend.js";
2
+ import { getSnapshot, sessionPath } from "./core/agents.js";
3
3
  import type { AgentFleet } from "./fleet/index.js";
4
- import { getSnapshot, sessionPath } from "./herdr.js";
5
4
  import { spawnedChildren } from "./spawn-ownership.js";
6
5
 
7
6
  export async function closeIdleChildren(
@@ -46,13 +45,7 @@ export async function closeIdleChildren(
46
45
  panel.agent !== "pi" ||
47
46
  panel.terminal_id !== child.terminal ||
48
47
  sessionPath(panel) !== child.sessionFile ||
49
- (runtime.local &&
50
- panel.pane_id ===
51
- process.env[
52
- runtime.client instanceof CoreConnection
53
- ? "HC_TERMINAL_ID"
54
- : "HERDR_PANE_ID"
55
- ]) ||
48
+ (runtime.local && panel.pane_id === process.env["HC_TERMINAL_ID"]) ||
56
49
  snapshot.agents.some(
57
50
  (value) =>
58
51
  value.pane_id !== child.pane &&
@@ -15,12 +15,10 @@ export function controlPanelStatus(options: PanelOptions): string {
15
15
  ),
16
16
  ...(!options.fleet.isActive()
17
17
  ? [
18
- "Fleet inactive. Run Pi inside Herdr; open /herdr → Status to reconnect.",
18
+ "Fleet inactive. Run Pi inside a Core terminal; open /herdr → Status to reconnect.",
19
19
  ]
20
20
  : []),
21
- process.env["HC_TERMINAL_SOCKET"]
22
- ? "Open /herdr in TUI for Settings and Status. Manage machines in Herdr or with hc machine add."
23
- : "Open /herdr in TUI for Settings, Status and SSH Connections.",
21
+ "Open /herdr in TUI for Settings, Status and Connections.",
24
22
  ].join("\n");
25
23
  }
26
24
 
@@ -16,14 +16,6 @@ export function buildPanelItems(
16
16
  draft: SshSetupDraft,
17
17
  ): SettingItem[] {
18
18
  if (tab === "Connections") {
19
- if (process.env["HC_TERMINAL_SOCKET"])
20
- return [
21
- {
22
- id: "core-machines",
23
- label: "Manage machines in Herdr or with hc machine add",
24
- currentValue: "",
25
- },
26
- ];
27
19
  return sshSetupItems(draft);
28
20
  }
29
21
  if (tab === "Status")
@@ -33,9 +25,7 @@ export function buildPanelItems(
33
25
  label: "Refresh and reconnect",
34
26
  currentValue: "Enter",
35
27
  values: ["Enter"],
36
- description: process.env["HC_TERMINAL_SOCKET"]
37
- ? "Refresh Core machines and retry connections."
38
- : "Reload Herdr profiles and retry connections.",
28
+ description: "Refresh Core machines and retry connections.",
39
29
  },
40
30
  ...options.fleet.statuses().map((machine) => ({
41
31
  id: `machine:${machine.id}`,
@@ -147,15 +147,9 @@ export class PanelView {
147
147
  ),
148
148
  "",
149
149
  ...wrap(
150
- this.tab === "Settings"
151
- ? ""
152
- : this.tab === "Connections"
153
- ? process.env["HC_TERMINAL_SOCKET"]
154
- ? ""
155
- : "Remote needs Node on SSH PATH and Pi with Herdr integration. Herdr prepares its server before saving."
156
- : process.env["HC_TERMINAL_SOCKET"]
157
- ? "Select a machine to reconnect."
158
- : `${this.owners.fleet.isActive() ? "" : "Run Pi inside Herdr. "}Add SSH targets in Connections; select a machine here to reconnect.`,
150
+ this.tab === "Status" && !this.owners.fleet.isActive()
151
+ ? "Run Pi inside a Core terminal."
152
+ : "",
159
153
  ).filter((line) => line.trim()),
160
154
  "",
161
155
  ];
package/src/controller.ts CHANGED
@@ -224,10 +224,7 @@ async function activateController(
224
224
  fleet: AgentFleet,
225
225
  ctx: ExtensionContext,
226
226
  ): Promise<boolean> {
227
- if (
228
- !(process.env["HC_TERMINAL_ID"] && process.env["HC_TERMINAL_SOCKET"]) &&
229
- (process.env["HERDR_ENV"] !== "1" || !process.env["HERDR_SOCKET_PATH"])
230
- ) {
227
+ if (!process.env["HC_TERMINAL_ID"] || !process.env["HC_TERMINAL_SOCKET"]) {
231
228
  ctx.ui.notify("Shepherdr requires Pi to run inside Herdr", "error");
232
229
  return false;
233
230
  }
@@ -1,6 +1,9 @@
1
1
  - Shared `pane_id` is an internal address key here, not a window pane identity. Emit terminal identity; never manufacture layout/focus IDs. Scope remote addresses by permanent Core ID, not session names or mutable machine aliases.
2
2
  - Agent launches pass `caller` to the originating Core so it qualifies remote parent links. `parent` resolves on the target Core and can select an unrelated terminal with the same local ID. Keep `no_notify`, not `no_parent`: sidebar ancestry and notification delivery are separate.
3
- - Remote subscriptions are invalidations: Core 0.1.14 retains old aliases after rename. Host aggregate lists omit slow machines, so supervision reads the selected Core's own list through the verified helper. An empty startup mirror requires a direct get, not rollback.
4
- - Remote helper bundling reuses the unchanged native peer/session/context readers. Keep its data-URL relative-import map complete when those helpers gain dependencies; never edit or deploy over the legacy bridge.
5
- - Closing a plain Core request does not cancel accepted remote execution. Keep remote watches and exec watchdogs bounded; abort local callbacks before releasing their monitor/client owner.
6
- - Fleet teardown is synchronous. Context relay route ownership spans replacement connections: fence startup behind the previous owner's completed close, including accepted startup, and release route entries after bounded cleanup. Keep relay payload limits aligned in remote-relay.ts and context-relay.mjs; poll batches must fit raw exec/context limits after JSON escaping, not just each request.
3
+ - Host aggregate terminal lists can omit slow remotes. Use local event snapshots and the selected remote Core's own view; remote events invalidate watched records. An empty startup mirror requires a direct terminal.get, not rollback.
4
+ - remote-helper.ts bundles native peer/session/context readers as data URLs. Keep its explicit module map and rewritten relative imports complete when helper dependencies change. Bootstrap must stay below command-size limits; send the module bundle only after credited attachment admission, never install helper files or use machine.exec polling.
5
+ - Saved Notes reads bundle Notes' public session reader, manifest dependency and exact-session index lookup. Keep discovery and parsing there, retain cancellation and frame bounds, and reject oversized results rather than truncate saved data.
6
+ - Keep voice focus on its separate private helper so large Notes payloads cannot block the voice channel. App focus must verify a window on the target Core, not infer window identity from terminal IDs.
7
+ - Closing a request does not cancel accepted remote work. Preserve uncertain-delivery errors, bound startup and cleanup, and abort callbacks before releasing their owner. A helper accepted after cancellation must still be killed; its wire lease bounds cleanup after route loss.
8
+ - Fleet teardown is synchronous, helper close is asynchronous. Context routes in remote-transport.ts span replacement connections: await the previous owner's completed close before route startup, then remove only your own route entry after bounded cleanup. Keep frame/context limits aligned across transport, wire and helper.
9
+ - Admission ends at native readiness or read completion, never worker settlement. Keep control, subscriptions and reverse context calls outside its lanes. Core's 16-exec limit does not apply to native terminal launches. Broker loss must never replay accepted work or leak scheduling into model-facing results.
@@ -0,0 +1,235 @@
1
+ #!/usr/bin/env node
2
+ import { createServer } from "node:net";
3
+ import { pathToFileURL } from "node:url";
4
+ import {
5
+ readAdmissionStart,
6
+ releaseAdmissionStart,
7
+ } from "./admission-owner.mjs";
8
+
9
+ export const LANE_LIMITS = Object.freeze({ launch: 4, bulk: 8 });
10
+ export const MAX_FRAME_BYTES = 8 * 1024;
11
+ export const MAX_CLIENT_REQUESTS = 64;
12
+ export const MAX_REQUESTS = 1024;
13
+
14
+ /** @typedef {'launch' | 'bulk'} Lane */
15
+ /** @typedef {{lane: Lane, active: boolean}} Permit */
16
+ /** @typedef {{socket: import('node:net').Socket, requests: Map<string, Permit>, queues: Record<Lane, string[]>}} Client */
17
+ /** @typedef {{active: number, ready: Client[]}} LaneState */
18
+
19
+ /** The caller owns the private directory and stale-socket recovery.
20
+ * @param {string} socketPath
21
+ * @param {()=>Promise<void>} [releaseStartup]
22
+ */
23
+ export function startAdmissionBroker(
24
+ socketPath,
25
+ releaseStartup = async () => {},
26
+ ) {
27
+ /** @type {Set<Client>} */
28
+ const clients = new Set();
29
+ /** @type {Record<Lane, LaneState>} */
30
+ const lanes = {
31
+ launch: { active: 0, ready: [] },
32
+ bulk: { active: 0, ready: [] },
33
+ };
34
+ let requests = 0;
35
+ let stopping = false;
36
+ /** @type {ReturnType<typeof setTimeout> | undefined} */
37
+ let idle;
38
+ const server = createServer(connect);
39
+ let starting = true;
40
+ function started() {
41
+ if (!starting) return;
42
+ starting = false;
43
+ void releaseStartup().catch(() => {
44
+ process.exitCode = 1;
45
+ stop();
46
+ });
47
+ }
48
+
49
+ function stop() {
50
+ if (stopping) return;
51
+ stopping = true;
52
+ started();
53
+ clearTimeout(idle);
54
+ for (const client of clients) client.socket.destroy();
55
+ // net.Server owns unlinking its successfully bound Unix socket. Never
56
+ // unlink by pathname here: a losing EADDRINUSE contender owns nothing.
57
+ server.close();
58
+ }
59
+
60
+ /** @param {number} delay */
61
+ function armIdle(delay) {
62
+ clearTimeout(idle);
63
+ idle = setTimeout(stop, delay);
64
+ }
65
+
66
+ /** @param {Client} client @param {object} response */
67
+ function send(client, response) {
68
+ const frame = `${JSON.stringify(response)}\n`;
69
+ if (
70
+ Buffer.byteLength(frame) > MAX_FRAME_BYTES ||
71
+ client.socket.writableLength > MAX_FRAME_BYTES * MAX_CLIENT_REQUESTS
72
+ ) {
73
+ client.socket.destroy();
74
+ return;
75
+ }
76
+ client.socket.write(frame);
77
+ }
78
+
79
+ function drain() {
80
+ if (stopping) return;
81
+ for (const lane of /** @type {Lane[]} */ (["launch", "bulk"])) {
82
+ const state = lanes[lane];
83
+ while (state.active < LANE_LIMITS[lane] && state.ready.length) {
84
+ const client = state.ready.shift();
85
+ if (!client || client.socket.destroyed) continue;
86
+ const id = client.queues[lane].shift();
87
+ if (id === undefined) continue;
88
+ const permit = client.requests.get(id);
89
+ if (!permit) continue;
90
+ permit.active = true;
91
+ state.active++;
92
+ if (client.queues[lane].length) state.ready.push(client);
93
+ send(client, { id, state: "granted" });
94
+ }
95
+ }
96
+ }
97
+
98
+ /** @param {Client} client @param {string} id */
99
+ function release(client, id) {
100
+ const permit = client.requests.get(id);
101
+ // Idempotent cleanup allows cancellation to race a normal release.
102
+ if (!permit) return;
103
+ client.requests.delete(id);
104
+ requests--;
105
+ const state = lanes[permit.lane];
106
+ if (permit.active) state.active--;
107
+ else {
108
+ const queue = client.queues[permit.lane];
109
+ queue.splice(queue.indexOf(id), 1);
110
+ if (!queue.length)
111
+ state.ready = state.ready.filter((entry) => entry !== client);
112
+ }
113
+ }
114
+
115
+ /** @param {Client} client @param {Buffer} frame */
116
+ function receive(client, frame) {
117
+ const message = JSON.parse(
118
+ new TextDecoder("utf-8", { fatal: true }).decode(frame),
119
+ );
120
+ if (
121
+ !message ||
122
+ typeof message !== "object" ||
123
+ Array.isArray(message) ||
124
+ typeof message.id !== "string" ||
125
+ !message.id ||
126
+ !["acquire", "release", "cancel"].includes(message.op)
127
+ )
128
+ throw new Error("Invalid admission frame");
129
+ if (message.op !== "acquire") {
130
+ if (Object.keys(message).some((key) => key !== "id" && key !== "op"))
131
+ throw new Error("Invalid cleanup frame");
132
+ release(client, message.id);
133
+ drain();
134
+ return;
135
+ }
136
+ if (
137
+ (message.lane !== "bulk" && message.lane !== "launch") ||
138
+ Object.keys(message).some((key) => !["id", "op", "lane"].includes(key)) ||
139
+ client.requests.has(message.id)
140
+ )
141
+ throw new Error("Invalid acquire frame");
142
+ if (
143
+ client.requests.size >= MAX_CLIENT_REQUESTS ||
144
+ requests >= MAX_REQUESTS
145
+ ) {
146
+ send(client, {
147
+ id: message.id,
148
+ state: "error",
149
+ message: "Admission queue full",
150
+ });
151
+ return;
152
+ }
153
+ const lane = /** @type {Lane} */ (message.lane);
154
+ client.requests.set(message.id, { lane, active: false });
155
+ requests++;
156
+ if (!client.queues[lane].length) lanes[lane].ready.push(client);
157
+ client.queues[lane].push(message.id);
158
+ drain();
159
+ }
160
+
161
+ /** @param {import('node:net').Socket} socket */
162
+ function connect(socket) {
163
+ if (stopping) return socket.destroy();
164
+ clearTimeout(idle);
165
+ /** @type {Client} */
166
+ const client = {
167
+ socket,
168
+ requests: new Map(),
169
+ queues: { launch: [], bulk: [] },
170
+ };
171
+ clients.add(client);
172
+ let buffered = Buffer.alloc(0);
173
+ socket.on("error", () => socket.destroy());
174
+ socket.on("close", () => {
175
+ clients.delete(client);
176
+ for (const id of client.requests.keys()) release(client, id);
177
+ drain();
178
+ if (!clients.size && !stopping) armIdle(2000);
179
+ });
180
+ socket.on("data", (chunk) => {
181
+ try {
182
+ if (!Buffer.isBuffer(chunk)) throw new Error("Expected raw bytes");
183
+ // Bound the partial frame, not the chunk: one read can hold many frames.
184
+ let offset = 0;
185
+ while (offset < chunk.length && !socket.destroyed) {
186
+ const newline = chunk.indexOf(10, offset);
187
+ const end = newline < 0 ? chunk.length : newline;
188
+ if (buffered.length + end - offset + 1 > MAX_FRAME_BYTES)
189
+ throw new Error("Admission frame too large");
190
+ buffered = Buffer.concat([buffered, chunk.subarray(offset, end)]);
191
+ if (newline < 0) break;
192
+ receive(client, buffered);
193
+ buffered = Buffer.alloc(0);
194
+ offset = end + 1;
195
+ }
196
+ } catch {
197
+ socket.destroy();
198
+ }
199
+ });
200
+ }
201
+
202
+ server.on("error", (error) => {
203
+ process.exitCode = "code" in error && error.code === "EADDRINUSE" ? 0 : 1;
204
+ stop();
205
+ });
206
+ server.on("close", () => {
207
+ clearTimeout(idle);
208
+ process.removeListener("SIGTERM", stop);
209
+ process.removeListener("SIGINT", stop);
210
+ });
211
+ process.on("SIGTERM", stop);
212
+ process.on("SIGINT", stop);
213
+ try {
214
+ server.listen(socketPath, () => {
215
+ started();
216
+ armIdle(5000);
217
+ });
218
+ } catch {
219
+ process.exitCode = 1;
220
+ stop();
221
+ }
222
+ return server;
223
+ }
224
+
225
+ if (
226
+ process.argv[1] &&
227
+ import.meta.url === pathToFileURL(process.argv[1]).href
228
+ ) {
229
+ try {
230
+ const { endpoint, lease } = await readAdmissionStart();
231
+ startAdmissionBroker(endpoint, () => releaseAdmissionStart(lease));
232
+ } catch {
233
+ process.exitCode = 1;
234
+ }
235
+ }
@@ -0,0 +1,180 @@
1
+ import { spawn } from "node:child_process";
2
+ import { createHash, randomBytes } from "node:crypto";
3
+ import {
4
+ link,
5
+ lstat,
6
+ mkdir,
7
+ readFile,
8
+ realpath,
9
+ unlink,
10
+ writeFile,
11
+ } from "node:fs/promises";
12
+ import { createConnection, type Socket } from "node:net";
13
+ import { userInfo } from "node:os";
14
+ import { dirname, join } from "node:path";
15
+ import { fileURLToPath } from "node:url";
16
+ import { lockStartup, pause } from "./admission-startup.js";
17
+
18
+ const runtimeDirectory = () =>
19
+ join(userInfo().homedir, ".cache", "pi-shepherdr", "admission");
20
+
21
+ async function privateDirectory(directory: string): Promise<void> {
22
+ await mkdir(directory, { mode: 0o700, recursive: true });
23
+ const metadata = await lstat(directory);
24
+ if (
25
+ !metadata.isDirectory() ||
26
+ metadata.isSymbolicLink() ||
27
+ (process.getuid && metadata.uid !== process.getuid()) ||
28
+ (process.platform !== "win32" && (metadata.mode & 0o077) !== 0)
29
+ )
30
+ throw new Error(
31
+ "Private agent runtime directory is not secure; check its ownership and permissions",
32
+ );
33
+ }
34
+
35
+ /** A private, stable name; kernel-owned endpoints need no stale lock reclamation. */
36
+ export async function admissionEndpoint(
37
+ core: string,
38
+ destination: string,
39
+ ): Promise<string> {
40
+ const directory = runtimeDirectory();
41
+ await privateDirectory(directory);
42
+ const canonical =
43
+ process.platform === "win32" ? core.toLowerCase() : await realpath(core);
44
+ const key = createHash("sha256")
45
+ .update(JSON.stringify([canonical, destination]))
46
+ .digest("hex");
47
+ const path = join(directory, key);
48
+ const candidate = `${path}.${randomBytes(8).toString("hex")}`;
49
+ await writeFile(candidate, randomBytes(24).toString("hex"), {
50
+ flag: "wx",
51
+ mode: 0o600,
52
+ });
53
+ try {
54
+ // Publish complete contents atomically, including concurrent first clients.
55
+ await link(candidate, path);
56
+ } catch (error) {
57
+ if (!(error instanceof Error && "code" in error && error.code === "EEXIST"))
58
+ throw error;
59
+ } finally {
60
+ await unlink(candidate);
61
+ }
62
+ const token = await readFile(path, "utf8");
63
+ if (!/^[a-f0-9]{48}$/.test(token))
64
+ throw new Error(
65
+ "Agent runtime endpoint is invalid; remove the invalid runtime file and reconnect",
66
+ );
67
+ if (process.platform === "linux") return `\0pi-shepherdr-${token}`;
68
+ if (process.platform === "win32") return `\\\\.\\pipe\\pi-shepherdr-${token}`;
69
+ // Core already needs a short Unix socket directory. Do not put a second
70
+ // socket beneath an arbitrarily long home directory on Darwin/BSD.
71
+ const sockets = join(
72
+ dirname(canonical),
73
+ `pi-sh-${process.getuid?.() ?? "user"}`,
74
+ );
75
+ const endpoint = join(sockets, `${token.slice(0, 24)}.sock`);
76
+ if (Buffer.byteLength(endpoint) > 100)
77
+ throw new Error(
78
+ "Core runtime path is too long for agent operations; restart Core with a shorter runtime directory",
79
+ );
80
+ await privateDirectory(sockets);
81
+ return endpoint;
82
+ }
83
+
84
+ function connect(path: string, signal: AbortSignal): Promise<Socket> {
85
+ return new Promise((resolve, reject) => {
86
+ const socket = createConnection({ path });
87
+ const abort = () => failed(signal.reason);
88
+ const failed = (error: Error) => {
89
+ signal.removeEventListener("abort", abort);
90
+ socket.destroy();
91
+ reject(error);
92
+ };
93
+ socket.once("error", failed);
94
+ signal.addEventListener("abort", abort, { once: true });
95
+ if (signal.aborted) abort();
96
+ socket.once("connect", () => {
97
+ signal.removeEventListener("abort", abort);
98
+ socket.removeListener("error", failed);
99
+ resolve(socket);
100
+ });
101
+ });
102
+ }
103
+
104
+ /** Bind elects the owner; losing starters exit. Never retry an accepted operation. */
105
+ export async function connectAdmission(
106
+ path: string,
107
+ signal: AbortSignal,
108
+ ): Promise<Socket> {
109
+ const attempt = async () => {
110
+ try {
111
+ return await connect(path, signal);
112
+ } catch (error) {
113
+ if (
114
+ !(
115
+ error instanceof Error &&
116
+ "code" in error &&
117
+ ["ENOENT", "ECONNREFUSED"].includes(String(error.code))
118
+ )
119
+ )
120
+ throw error;
121
+ return undefined;
122
+ }
123
+ };
124
+ const existing = await attempt();
125
+ if (existing) return existing;
126
+ const filesystem =
127
+ !path.startsWith("\0") && !path.startsWith("\\\\.\\pipe\\");
128
+ const lockPath = filesystem
129
+ ? path
130
+ : join(runtimeDirectory(), createHash("sha256").update(path).digest("hex"));
131
+ const lock = await lockStartup(lockPath, signal);
132
+ let transferred = false;
133
+ try {
134
+ const owner = await attempt();
135
+ if (owner) return owner;
136
+ if (filesystem) {
137
+ // All filesystem binders hold this lock. A refused socket is stale,
138
+ // but cannot be unlinked outside election without racing a new owner.
139
+ await unlink(path).catch((error: unknown) => {
140
+ if (
141
+ !(
142
+ error instanceof Error &&
143
+ "code" in error &&
144
+ error.code === "ENOENT"
145
+ )
146
+ )
147
+ throw error;
148
+ });
149
+ }
150
+ signal.throwIfAborted();
151
+ const child = spawn(
152
+ process.execPath,
153
+ [
154
+ fileURLToPath(new URL("./admission-broker.mjs", import.meta.url)),
155
+ createHash("sha256").update(path).digest("hex"),
156
+ ],
157
+ {
158
+ detached: true,
159
+ stdio: ["pipe", "ignore", "ignore"],
160
+ windowsHide: true,
161
+ },
162
+ );
163
+ // Startup failure is reported through the bounded connection attempt.
164
+ child.on("error", () => {});
165
+ child.unref();
166
+ if (!child.pid) throw new Error("Agent runtime did not start");
167
+ const lease = await lock.handoff(child.pid);
168
+ transferred = true;
169
+ child.stdin.on("error", () => {});
170
+ child.stdin.end(JSON.stringify({ endpoint: path, lease }));
171
+ for (;;) {
172
+ signal.throwIfAborted();
173
+ const socket = await attempt();
174
+ if (socket) return socket;
175
+ await pause(signal);
176
+ }
177
+ } finally {
178
+ if (!transferred) await lock.release();
179
+ }
180
+ }
@@ -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
+ }