@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.
- package/CHANGELOG.md +5 -0
- package/README.md +40 -44
- package/index.ts +7 -1
- package/package.json +5 -5
- package/src/agent-identity.ts +3 -3
- package/src/agents-contract.ts +1 -5
- package/src/agents-discovery.ts +20 -46
- package/src/agents-focus.ts +21 -20
- package/src/agents-spawn.ts +4 -17
- package/src/agents-tool.ts +7 -20
- package/src/agents-work.ts +4 -3
- package/src/attachment-protocol.ts +1 -0
- package/src/attachment.ts +6 -2
- package/src/board/host.ts +1 -1
- package/src/close-idle.ts +2 -9
- package/src/control-panel/index.ts +2 -4
- package/src/control-panel/items.ts +1 -11
- package/src/control-panel/view.ts +3 -9
- package/src/controller.ts +1 -4
- package/src/core/AGENTS.md +8 -4
- package/src/core/admission-broker.mjs +235 -0
- package/src/core/admission-endpoint.ts +180 -0
- package/src/core/admission-owner.mjs +52 -0
- package/src/core/admission-startup.ts +130 -0
- package/src/core/admission.ts +181 -0
- package/src/core/agents.ts +102 -0
- package/src/core/backend.ts +116 -84
- package/src/core/client.ts +16 -0
- package/src/core/focus-channel-helper.mjs +6 -27
- package/src/core/focus-channel-wire.mjs +9 -6
- package/src/core/focus-channel.ts +5 -3
- package/src/core/focus-window.ts +15 -4
- package/src/core/helper-bootstrap.mjs +70 -0
- package/src/core/helper-context.mjs +98 -0
- package/src/core/helper-core.mjs +121 -0
- package/src/core/machines.ts +30 -0
- package/src/core/registration.ts +7 -2
- package/src/core/remote-endpoint.ts +80 -76
- package/src/core/remote-helper.ts +322 -0
- package/src/core/remote-reader.ts +3 -42
- package/src/core/remote-service.mjs +241 -0
- package/src/core/remote-transport.ts +290 -0
- package/src/core/spawn.ts +21 -21
- package/src/core/terminal-peer.mjs +57 -0
- package/src/core/terminal.ts +4 -2
- package/src/fleet/catalog.ts +16 -58
- package/src/fleet/connection.ts +9 -18
- package/src/fleet/index.ts +38 -76
- package/src/fleet/inspection.ts +9 -22
- package/src/fleet/machine.ts +28 -12
- package/src/fleet/monitor.ts +8 -29
- package/src/fleet/persistence.ts +2 -2
- package/src/fleet/reconnect.ts +5 -3
- package/src/fleet/setup.ts +6 -16
- package/src/launch-contract.ts +0 -3
- package/src/launch-location.ts +4 -132
- package/src/launch.ts +18 -144
- package/src/messages/attribution.ts +5 -13
- package/src/messages/events.ts +5 -9
- package/src/messages/focus.ts +2 -7
- package/src/monitor-events.ts +14 -43
- package/src/monitor-extension-messages.ts +5 -6
- package/src/monitor-record.ts +4 -0
- package/src/monitor-state.ts +1 -101
- package/src/monitor.ts +38 -66
- package/src/peer-inbox.ts +21 -27
- package/src/remote/context-relay.ts +25 -10
- package/src/remote/shepherdr-channel.mjs +1 -1
- package/src/remote/shepherdr-checkpoints.mjs +51 -102
- package/src/remote/shepherdr-context.mjs +1 -1
- package/src/remote/shepherdr-peer.mjs +19 -24
- package/src/saved-context.ts +62 -0
- package/src/settlement/collector.ts +29 -9
- package/src/settlement/index.ts +25 -6
- package/src/shared-context-host.ts +19 -3
- package/src/shared-context.ts +9 -3
- package/src/spawn-context.ts +9 -1
- package/src/spawn-ownership.ts +1 -1
- package/src/ssh-setup.ts +40 -73
- package/src/types.ts +4 -8
- package/src/widget.ts +7 -2
- package/src/worker-ownership.ts +2 -8
- package/src/worker-service.ts +3 -13
- package/src/core/context-relay.mjs +0 -111
- package/src/core/remote-exec.ts +0 -122
- package/src/core/remote-helper.mjs +0 -244
- package/src/core/remote-relay.ts +0 -191
- package/src/core/request.ts +0 -124
- package/src/herdr-client.ts +0 -364
- package/src/herdr.ts +0 -268
- package/src/machine-catalog.ts +0 -83
- package/src/monitor-event.ts +0 -84
- package/src/remote/client.ts +0 -127
- package/src/remote/deployment.ts +0 -179
- package/src/remote/focus-channels.ts +0 -89
- package/src/remote/shepherdr.mjs +0 -504
- package/src/remote/transport.ts +0 -369
package/src/agents-tool.ts
CHANGED
|
@@ -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 {
|
|
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: [
|
|
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({
|
package/src/agents-work.ts
CHANGED
|
@@ -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<
|
|
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
|
-
|
|
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 {
|
|
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
|
|
18
|
+
"Fleet inactive. Run Pi inside a Core terminal; open /herdr → Status to reconnect.",
|
|
19
19
|
]
|
|
20
20
|
: []),
|
|
21
|
-
|
|
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:
|
|
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 === "
|
|
151
|
-
? ""
|
|
152
|
-
:
|
|
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
|
}
|
package/src/core/AGENTS.md
CHANGED
|
@@ -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
|
-
-
|
|
3
|
-
-
|
|
4
|
-
-
|
|
5
|
-
-
|
|
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
|
+
}
|