@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
@@ -27,9 +27,8 @@ import {
27
27
  toolResult,
28
28
  } from "./agents-work.js";
29
29
  import type { AgentBoard } from "./board/host.js";
30
- import { CoreConnection } from "./core/backend.js";
30
+ import { resolvePiAgent } from "./core/agents.js";
31
31
  import type { AgentFleet } from "./fleet/index.js";
32
- import { resolvePiAgent } from "./herdr.js";
33
32
  import { attributeAgentPrompt } from "./messages/attribution.js";
34
33
  import type { createPeerCommands } from "./peer-commands.js";
35
34
  import type { SharedAgentContext } from "./shared-context.js";
@@ -47,7 +46,10 @@ export function createAgentsTool(
47
46
  label: "Shepherdr",
48
47
  description:
49
48
  "Delegate to persistent agents; {} lists additional action fields",
50
- promptGuidelines: ["agents: Read help alone first"],
49
+ promptGuidelines: [
50
+ "agents: Read help alone first",
51
+ "agents: MUST use for supported agent operations, local or remote; never bypass with hc or shell commands, even after failure. Report blockers. hc remains available for non-agent processes",
52
+ ],
51
53
  parameters: AgentsParameters,
52
54
  executionMode: "parallel",
53
55
  async execute(_toolCallId, input: AgentsToolParams, signal, onUpdate, ctx) {
@@ -55,16 +57,7 @@ export function createAgentsTool(
55
57
  const executionSignal = signal ?? new AbortController().signal;
56
58
  const update = onUpdate ?? (() => undefined);
57
59
  if (params.action === "help" && !params.commands) {
58
- return toolResult(
59
- await agentsHelp(
60
- board.enabled(ctx),
61
- gpt(),
62
- Boolean(
63
- process.env["HC_TERMINAL_ID"] &&
64
- process.env["HC_TERMINAL_SOCKET"],
65
- ),
66
- ),
67
- );
60
+ return toolResult(await agentsHelp(board.enabled(ctx), gpt()));
68
61
  }
69
62
  if (params.commands && params.target === undefined)
70
63
  return toolResult({ commands: commands.available() });
@@ -145,13 +138,7 @@ export function createAgentsTool(
145
138
  const panel = await resolvePiAgent(
146
139
  runtime.client,
147
140
  target,
148
- runtime.local
149
- ? process.env[
150
- runtime.client instanceof CoreConnection
151
- ? "HC_TERMINAL_ID"
152
- : "HERDR_PANE_ID"
153
- ]
154
- : "",
141
+ runtime.local ? process.env["HC_TERMINAL_ID"] : "",
155
142
  );
156
143
  if (params.commands) {
157
144
  return toolResult({
@@ -1,10 +1,11 @@
1
1
  import type { AgentToolUpdateCallback } from "@earendil-works/pi-coding-agent";
2
2
  import { activityTask } from "./activity.js";
3
+ import { getSnapshot } from "./core/agents.js";
4
+ import type { CoreConnection } from "./core/backend.js";
3
5
  import type { ConnectedMachine } from "./fleet/index.js";
4
- import { getSnapshot } from "./herdr.js";
5
- import { type HerdrConnection, isDispatchRejected } from "./herdr-client.js";
6
6
  import { agentSource } from "./messages/attribution.js";
7
7
  import type { WorkAttempt } from "./monitor-state.js";
8
+ import { isDispatchRejected } from "./remote/shepherdr-peer.mjs";
8
9
  import type { ClaimedSettlement } from "./settlement/index.js";
9
10
  import type { ExtensionReply, PaneInfo, PeerDelivery } from "./types.js";
10
11
 
@@ -38,7 +39,7 @@ function slugify(value: string): string {
38
39
  return named.slice(0, 32).replace(/-+$/u, "") || "agent";
39
40
  }
40
41
 
41
- const startingNames = new WeakMap<HerdrConnection, Set<string>>();
42
+ const startingNames = new WeakMap<CoreConnection, Set<string>>();
42
43
 
43
44
  export async function reserveAgentName(
44
45
  runtime: ConnectedMachine,
@@ -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,5 +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
- - 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.
3
- - 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.
4
- - 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.
5
- - 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.
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
+ - 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
+ }