@howaboua/pi-shepherdr 0.2.27 → 0.2.28-core.12.1.gda85fa2e8a0f

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 (112) hide show
  1. package/README.md +48 -48
  2. package/index.ts +7 -1
  3. package/package.json +2 -9
  4. package/src/agent-identity.ts +3 -3
  5. package/src/agents-contract.ts +10 -14
  6. package/src/agents-discovery.ts +34 -54
  7. package/src/agents-focus.ts +23 -35
  8. package/src/agents-spawn.ts +24 -23
  9. package/src/agents-tool.ts +4 -19
  10. package/src/agents-work.ts +4 -3
  11. package/src/attachment-notes.ts +8 -7
  12. package/src/attachment-protocol.ts +3 -2
  13. package/src/attachment-routing.ts +1 -1
  14. package/src/attachment-target.ts +10 -18
  15. package/src/attachment.ts +14 -9
  16. package/src/board/discovery.ts +67 -0
  17. package/src/board/host.ts +93 -63
  18. package/src/board/membership.ts +16 -11
  19. package/src/board/records.ts +185 -0
  20. package/src/close-idle.ts +2 -9
  21. package/src/context-briefing.ts +230 -0
  22. package/src/context-routing.ts +1 -1
  23. package/src/control-panel/index.ts +2 -4
  24. package/src/control-panel/items.ts +1 -11
  25. package/src/control-panel/view.ts +3 -9
  26. package/src/controller.ts +50 -63
  27. package/src/core/AGENTS.md +7 -4
  28. package/src/core/admission-broker.mjs +235 -0
  29. package/src/core/admission-endpoint.ts +180 -0
  30. package/src/core/admission-owner.mjs +52 -0
  31. package/src/core/admission-startup.ts +130 -0
  32. package/src/core/admission.ts +181 -0
  33. package/src/core/agents.ts +102 -0
  34. package/src/core/backend.ts +110 -84
  35. package/src/core/client.ts +16 -0
  36. package/src/core/focus-channel-helper.mjs +6 -27
  37. package/src/core/focus-channel-wire.mjs +9 -6
  38. package/src/core/focus-channel.ts +5 -3
  39. package/src/core/focus-window.ts +15 -4
  40. package/src/core/helper-bootstrap.mjs +70 -0
  41. package/src/core/helper-context.mjs +98 -0
  42. package/src/core/helper-core.mjs +121 -0
  43. package/src/core/machines.ts +30 -0
  44. package/src/core/registration.ts +7 -2
  45. package/src/core/remote-endpoint.ts +80 -74
  46. package/src/core/remote-helper.ts +330 -0
  47. package/src/core/remote-reader.ts +3 -42
  48. package/src/core/remote-service.mjs +239 -0
  49. package/src/core/remote-transport.ts +290 -0
  50. package/src/core/spawn.ts +20 -20
  51. package/src/core/terminal-peer.mjs +57 -0
  52. package/src/core/terminal.ts +4 -2
  53. package/src/delivery.ts +39 -0
  54. package/src/fleet/catalog.ts +16 -58
  55. package/src/fleet/connection.ts +9 -18
  56. package/src/fleet/index.ts +38 -76
  57. package/src/fleet/inspection.ts +9 -22
  58. package/src/fleet/machine.ts +28 -12
  59. package/src/fleet/monitor.ts +8 -29
  60. package/src/fleet/persistence.ts +2 -2
  61. package/src/fleet/reconnect.ts +5 -3
  62. package/src/fleet/setup.ts +6 -16
  63. package/src/launch-contract.ts +0 -3
  64. package/src/launch-location.ts +4 -132
  65. package/src/launch.ts +18 -144
  66. package/src/messages/attachments.ts +1 -1
  67. package/src/messages/attribution.ts +9 -14
  68. package/src/messages/events.ts +5 -9
  69. package/src/messages/focus.ts +2 -7
  70. package/src/messages/guidance.ts +2 -43
  71. package/src/messages/peer-sharing.ts +133 -0
  72. package/src/monitor-events.ts +14 -43
  73. package/src/monitor-extension-messages.ts +5 -6
  74. package/src/monitor-record.ts +4 -0
  75. package/src/monitor-state.ts +1 -101
  76. package/src/monitor.ts +38 -66
  77. package/src/notes-discovery.ts +67 -0
  78. package/src/peer-inbox.ts +21 -27
  79. package/src/remote/context-relay.ts +25 -10
  80. package/src/remote/notes-reader.mjs +67 -0
  81. package/src/remote/shepherdr-channel.mjs +1 -1
  82. package/src/remote/shepherdr-checkpoints.mjs +49 -102
  83. package/src/remote/shepherdr-context.mjs +1 -1
  84. package/src/remote/shepherdr-peer.mjs +19 -24
  85. package/src/remote/shepherdr-session.mjs +18 -7
  86. package/src/saved-context.ts +62 -0
  87. package/src/settlement/collector.ts +29 -9
  88. package/src/settlement/index.ts +35 -6
  89. package/src/shared-context-host.ts +27 -33
  90. package/src/shared-context.ts +44 -15
  91. package/src/spawn-context.ts +11 -3
  92. package/src/spawn-ownership.ts +1 -1
  93. package/src/ssh-setup.ts +40 -73
  94. package/src/types.ts +4 -8
  95. package/src/voice-handoff.ts +1 -1
  96. package/src/widget.ts +7 -2
  97. package/src/worker-ownership.ts +2 -8
  98. package/src/worker-service.ts +6 -14
  99. package/src/core/context-relay.mjs +0 -111
  100. package/src/core/remote-exec.ts +0 -122
  101. package/src/core/remote-helper.mjs +0 -244
  102. package/src/core/remote-relay.ts +0 -191
  103. package/src/core/request.ts +0 -124
  104. package/src/herdr-client.ts +0 -364
  105. package/src/herdr.ts +0 -268
  106. package/src/machine-catalog.ts +0 -83
  107. package/src/monitor-event.ts +0 -84
  108. package/src/remote/client.ts +0 -127
  109. package/src/remote/deployment.ts +0 -179
  110. package/src/remote/focus-channels.ts +0 -89
  111. package/src/remote/shepherdr.mjs +0 -504
  112. package/src/remote/transport.ts +0 -369
@@ -1,504 +0,0 @@
1
- // @howaboua/pi-shepherdr managed bridge
2
- import { readFile, stat } from "node:fs/promises";
3
- import { createConnection } from "node:net";
4
- import { homedir, hostname } from "node:os";
5
- import { join, resolve } from "node:path";
6
- import { openPeerChannel } from "./shepherdr-channel.mjs";
7
- import {
8
- listenContext,
9
- relayContextPath,
10
- requestContext,
11
- } from "./shepherdr-context.mjs";
12
- import {
13
- sendPeerCommands,
14
- sendPeerExtensionReply,
15
- sendPeerFocus,
16
- sendPeerMessage,
17
- } from "./shepherdr-peer.mjs";
18
- import { readSessionView } from "./shepherdr-session.mjs";
19
- import { watchSessions } from "./shepherdr-session-watch.mjs";
20
-
21
- const BRIDGE_VERSION = 23;
22
- const MAX_FRAME_BYTES = 8 * 1024 * 1024;
23
- const subscriptions = new Map();
24
- const contextRelays = new Map();
25
- const contextRequests = new Map();
26
- const contextCalls = new Map();
27
- const channels = new Map();
28
-
29
- function requestController(request, signal) {
30
- signal.throwIfAborted();
31
- const id = crypto.randomUUID();
32
- return new Promise((resolve, reject) => {
33
- const finish = (error, result) => {
34
- if (!contextRequests.delete(id)) return;
35
- clearTimeout(timer);
36
- signal.removeEventListener("abort", abort);
37
- if (error) reject(error);
38
- else resolve(result);
39
- };
40
- const abort = () => {
41
- send({ type: "context_cancel", id });
42
- finish(
43
- new Error(
44
- "Shared context request cancelled; a write may have completed. Reread before retrying",
45
- ),
46
- );
47
- };
48
- const timer = setTimeout(() => {
49
- send({ type: "context_cancel", id });
50
- finish(
51
- new Error(
52
- "Shared context controller did not reply; a write may have completed. Reread before retrying",
53
- ),
54
- );
55
- }, 35_000);
56
- timer.unref();
57
- contextRequests.set(id, {
58
- resolve: (result) => finish(undefined, result),
59
- reject: (error) => finish(error),
60
- });
61
- signal.addEventListener("abort", abort, { once: true });
62
- send({ type: "context_request", id, request });
63
- });
64
- }
65
-
66
- function argument(name) {
67
- const index = process.argv.indexOf(`--${name}`);
68
- return index >= 0 ? process.argv[index + 1] : undefined;
69
- }
70
-
71
- function expandHome(path) {
72
- return path === "~"
73
- ? homedir()
74
- : path.startsWith("~/")
75
- ? join(homedir(), path.slice(2))
76
- : path;
77
- }
78
-
79
- function socketPath() {
80
- const root = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
81
- const session = argument("session");
82
- if (
83
- !session ||
84
- !/^[a-zA-Z0-9_.-]{1,64}$/.test(session) ||
85
- session === "." ||
86
- session === ".."
87
- ) {
88
- throw new Error("A valid Herdr --session is required");
89
- }
90
- return session !== "default"
91
- ? join(root, "herdr", "sessions", session, "herdr.sock")
92
- : join(root, "herdr", "herdr.sock");
93
- }
94
-
95
- function send(value) {
96
- const frame = `${JSON.stringify(value)}\n`;
97
- if (Buffer.byteLength(frame) > MAX_FRAME_BYTES) {
98
- throw new Error("Shepherdr bridge response is too large");
99
- }
100
- process.stdout.write(frame);
101
- }
102
-
103
- function responseError(value) {
104
- if (value && typeof value === "object" && typeof value.message === "string") {
105
- return {
106
- message: value.message,
107
- ...(typeof value.code === "string" ? { code: value.code } : {}),
108
- herdrResponse: true,
109
- };
110
- }
111
- return {
112
- message: `Herdr request failed: ${JSON.stringify(value)}`,
113
- herdrResponse: true,
114
- };
115
- }
116
-
117
- function errorFromResponse(value) {
118
- const detail = responseError(value);
119
- return Object.assign(new Error(detail.message), detail);
120
- }
121
-
122
- function openHerdr(label, message, onValue, onDisconnect) {
123
- let buffer = "";
124
- let disconnected = false;
125
- const socket = createConnection(socketPath());
126
- const disconnect = (error) => {
127
- if (disconnected) return;
128
- disconnected = true;
129
- onDisconnect(error ?? new Error(`${label} disconnected`));
130
- };
131
- socket.setEncoding("utf8");
132
- socket.on("connect", () => socket.write(`${JSON.stringify(message)}\n`));
133
- socket.on("error", disconnect);
134
- socket.on("end", () => disconnect());
135
- socket.on("close", () => disconnect());
136
- socket.on("data", (chunk) => {
137
- buffer += chunk;
138
- if (Buffer.byteLength(buffer) > MAX_FRAME_BYTES) {
139
- disconnect(new Error(`${label} frame is too large`));
140
- socket.destroy();
141
- return;
142
- }
143
- for (;;) {
144
- const newline = buffer.indexOf("\n");
145
- if (newline < 0) break;
146
- const line = buffer.slice(0, newline);
147
- buffer = buffer.slice(newline + 1);
148
- if (!line) continue;
149
- let value;
150
- try {
151
- value = JSON.parse(line);
152
- } catch (error) {
153
- disconnect(
154
- new Error(`${label} returned invalid JSON: ${error.message}`),
155
- );
156
- socket.destroy();
157
- return;
158
- }
159
- onValue(value);
160
- }
161
- });
162
- return socket;
163
- }
164
-
165
- function request(method, params = {}, timeoutMs = 10_000) {
166
- return new Promise((resolveRequest, reject) => {
167
- const id = `pi-shepherdr-bridge:${crypto.randomUUID()}`;
168
- let settled = false;
169
- let socket;
170
- const timer = setTimeout(
171
- () => finish(new Error(`Herdr ${method} timed out`)),
172
- timeoutMs,
173
- );
174
- timer.unref();
175
- const finish = (error, result) => {
176
- if (settled) return;
177
- settled = true;
178
- clearTimeout(timer);
179
- socket.destroy();
180
- if (error) reject(error);
181
- else resolveRequest(result);
182
- };
183
- socket = openHerdr(
184
- `Herdr ${method}`,
185
- { id, method, params },
186
- (response) => {
187
- if (response.id !== id)
188
- finish(
189
- new Error(`Herdr ${method} returned a mismatched response ID`),
190
- );
191
- else if (response.error !== undefined)
192
- finish(errorFromResponse(response.error));
193
- else if (response.result !== undefined)
194
- finish(undefined, response.result);
195
- else finish(new Error(`Herdr ${method} returned no result`));
196
- },
197
- (error) => finish(error),
198
- );
199
- });
200
- }
201
-
202
- function subscribe(id, requested) {
203
- return new Promise((resolveSubscription, reject) => {
204
- const requestId = `pi-shepherdr-bridge:subscribe:${crypto.randomUUID()}`;
205
- let acknowledged = false;
206
- let closed = false;
207
- let ended = false;
208
- let socket;
209
- const timer = setTimeout(
210
- () => disconnected(new Error("Herdr events.subscribe timed out")),
211
- 10_000,
212
- );
213
- timer.unref();
214
- const disconnected = (error) => {
215
- if (ended) return;
216
- ended = true;
217
- clearTimeout(timer);
218
- subscriptions.delete(id);
219
- socket.destroy();
220
- if (!acknowledged)
221
- reject(
222
- error ??
223
- new Error("Herdr events.subscribe closed before acknowledgement"),
224
- );
225
- else if (!closed) {
226
- process.stderr.write(
227
- `Herdr monitoring disconnected${error ? `: ${error.message}` : ""}\n`,
228
- );
229
- process.exitCode = 1;
230
- setTimeout(() => process.exit(), 0);
231
- }
232
- };
233
- socket = openHerdr(
234
- "Herdr events.subscribe",
235
- {
236
- id: requestId,
237
- method: "events.subscribe",
238
- params: { subscriptions: requested },
239
- },
240
- (value) => {
241
- if (ended) return;
242
- if (value.id === requestId && value.error !== undefined) {
243
- disconnected(errorFromResponse(value.error));
244
- return;
245
- }
246
- if (!acknowledged && value.id === requestId) {
247
- if (value.result?.type !== "subscription_started") {
248
- disconnected(
249
- new Error(
250
- "Herdr events.subscribe returned an invalid acknowledgement",
251
- ),
252
- );
253
- socket.destroy();
254
- return;
255
- }
256
- acknowledged = true;
257
- clearTimeout(timer);
258
- resolveSubscription();
259
- return;
260
- }
261
- if (
262
- acknowledged &&
263
- typeof value.event === "string" &&
264
- value.data &&
265
- typeof value.data === "object"
266
- ) {
267
- send({
268
- subscription: id,
269
- event: { event: value.event, data: value.data },
270
- });
271
- }
272
- },
273
- disconnected,
274
- );
275
- subscriptions.set(id, () => {
276
- closed = true;
277
- disconnected(new Error("Herdr subscription cancelled"));
278
- });
279
- });
280
- }
281
-
282
- async function directory(value, fallback) {
283
- const base = expandHome(fallback?.trim() || homedir());
284
- const path = resolve(base, expandHome(value?.trim() || "."));
285
- const metadata = await stat(path).catch((error) => {
286
- throw new Error(
287
- `cannot use working directory ${JSON.stringify(path)}: ${error.message}`,
288
- );
289
- });
290
- if (!metadata.isDirectory())
291
- throw new Error(`${JSON.stringify(path)} is not a directory`);
292
- return path;
293
- }
294
-
295
- async function keybindings() {
296
- const directory =
297
- process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
298
- try {
299
- const value = JSON.parse(
300
- await readFile(join(directory, "keybindings.json"), "utf8"),
301
- );
302
- return value && typeof value === "object" ? value : {};
303
- } catch {
304
- return {};
305
- }
306
- }
307
-
308
- function serializableError(error) {
309
- return {
310
- message: error instanceof Error ? error.message : String(error),
311
- ...(typeof error?.code === "string" ? { code: error.code } : {}),
312
- ...(error?.herdrResponse === true ? { herdrResponse: true } : {}),
313
- };
314
- }
315
-
316
- async function handle(message) {
317
- if (
318
- !message ||
319
- typeof message !== "object" ||
320
- typeof message.id !== "string" ||
321
- typeof message.op !== "string"
322
- ) {
323
- throw new Error("invalid Shepherdr bridge request");
324
- }
325
- if (message.op === "request") {
326
- return request(message.method, message.params ?? {}, message.timeoutMs);
327
- }
328
- if (message.op === "message") {
329
- return sendPeerMessage(request, message.agent, message.message);
330
- }
331
- if (message.op === "extension-reply")
332
- return sendPeerExtensionReply(request, message.agent, message.reply);
333
- if (message.op === "identity") {
334
- return { host: hostname(), session: argument("session") || "default" };
335
- }
336
- if (message.op === "focus") {
337
- return sendPeerFocus(request, message.agent, message.request);
338
- }
339
- if (message.op === "commands") {
340
- return sendPeerCommands(request, message.agent);
341
- }
342
- if (message.op === "channel_open") {
343
- const channel = await openPeerChannel(
344
- request,
345
- message.agent,
346
- message.request,
347
- );
348
- channels.set(message.id, channel);
349
- channel.onClose((error) => {
350
- channels.delete(message.id);
351
- send({
352
- type: "channel",
353
- channel: message.id,
354
- closed: true,
355
- error: error.message,
356
- });
357
- });
358
- channel.onMessage((frame) => {
359
- if (process.stdout.writableLength > 1024 * 1024)
360
- throw new Error("Focus channel bridge output exceeded its buffer");
361
- send({ type: "channel", channel: message.id, message: frame });
362
- });
363
- return { admitted: true };
364
- }
365
- if (message.op === "context") {
366
- const controller = new AbortController();
367
- contextCalls.set(message.id, controller);
368
- try {
369
- return await requestContext(
370
- message.path,
371
- message.request,
372
- controller.signal,
373
- );
374
- } finally {
375
- contextCalls.delete(message.id);
376
- }
377
- }
378
- if (message.op === "context_relay") {
379
- const path = relayContextPath(message.threadId, message.routeId);
380
- if (!contextRelays.has(path))
381
- contextRelays.set(path, await listenContext(path, requestController));
382
- return path;
383
- }
384
- if (message.op === "subscribe") {
385
- await subscribe(message.id, message.subscriptions ?? []);
386
- return { subscribed: true };
387
- }
388
- if (message.op === "session_subscribe") {
389
- const close = watchSessions(
390
- message.paths ?? [],
391
- (path) =>
392
- send({
393
- subscription: message.id,
394
- event: { event: "session.changed", data: { path } },
395
- }),
396
- (error) => {
397
- process.stderr.write(
398
- `Session monitoring disconnected: ${error.message}\n`,
399
- );
400
- process.exitCode = 1;
401
- setTimeout(() => process.exit(), 0);
402
- },
403
- );
404
- subscriptions.set(message.id, close);
405
- return { subscribed: true };
406
- }
407
- if (message.op === "unsubscribe") {
408
- subscriptions.get(message.subscription)?.();
409
- subscriptions.delete(message.subscription);
410
- return { unsubscribed: true };
411
- }
412
- if (message.op === "view") return readSessionView(message.path);
413
- if (message.op === "keybindings") return keybindings();
414
- if (message.op === "directory")
415
- return directory(message.value, message.fallback);
416
- throw new Error(`unsupported Shepherdr bridge operation ${message.op}`);
417
- }
418
-
419
- let input = "";
420
- process.stdin.setEncoding("utf8");
421
- process.stdin.on("data", (chunk) => {
422
- input += chunk;
423
- if (Buffer.byteLength(input) > MAX_FRAME_BYTES) {
424
- process.stderr.write("Shepherdr bridge request is too large\n");
425
- process.exit(1);
426
- }
427
- for (;;) {
428
- const newline = input.indexOf("\n");
429
- if (newline < 0) break;
430
- const line = input.slice(0, newline);
431
- input = input.slice(newline + 1);
432
- if (!line) continue;
433
- let message;
434
- try {
435
- message = JSON.parse(line);
436
- } catch (error) {
437
- send({ id: "invalid", ok: false, error: serializableError(error) });
438
- continue;
439
- }
440
- if (message?.op === "context_cancel") {
441
- contextCalls.get(message.id)?.abort();
442
- continue;
443
- }
444
- if (message?.op === "channel_send" || message?.op === "channel_close") {
445
- const channel = channels.get(message.id);
446
- try {
447
- if (message.op === "channel_close") channel?.close();
448
- else if (channel) channel.send(message.message);
449
- else
450
- send({
451
- type: "channel",
452
- channel: message.id,
453
- closed: true,
454
- error: "Focus channel is unavailable",
455
- });
456
- } catch (error) {
457
- channel?.close();
458
- }
459
- continue;
460
- }
461
- if (message?.op === "context_reply") {
462
- const pending = contextRequests.get(message.id);
463
- if (pending) {
464
- if (message.ok === true) pending.resolve(message.result);
465
- else
466
- pending.reject(
467
- new Error(
468
- typeof message.error === "string"
469
- ? message.error
470
- : "Shared context controller failed",
471
- ),
472
- );
473
- }
474
- continue;
475
- }
476
- void handle(message).then(
477
- (result) => send({ id: message.id, ok: true, result }),
478
- (error) =>
479
- send({ id: message.id, ok: false, error: serializableError(error) }),
480
- );
481
- }
482
- });
483
-
484
- async function shutdown() {
485
- for (const channel of channels.values()) channel.close();
486
- for (const close of subscriptions.values()) close();
487
- for (const controller of contextCalls.values()) controller.abort();
488
- await Promise.allSettled([...contextRelays.values()].map((close) => close()));
489
- process.exit();
490
- }
491
- process.stdin.on("end", () => {
492
- void shutdown();
493
- });
494
- for (const signal of ["SIGINT", "SIGTERM"]) {
495
- process.on(signal, () => {
496
- void shutdown();
497
- });
498
- }
499
-
500
- send({
501
- type: "ready",
502
- version: BRIDGE_VERSION,
503
- socket: socketPath(),
504
- });